ssh

gliderlabs/ssh wraps Go’s low-level crypto/ssh package with an API deliberately modeled on net/http: ssh.ListenAndServe and ssh.Handle mirror their HTTP counterparts, so a Go developer already comfortable writing HTTP handlers can write an SSH server handler with almost no new mental model. A Session is exposed as an io.ReadWriter with SSH-specific accessors for the remote command, environment variables, PTY/window-resize events, and POSIX signals, letting a handler treat an SSH connection much like an HTTP request.

Authentication, port forwarding, and host-key management are all opt-in via small functional options (PasswordAuth, PublicKeyAuth, KeyboardInteractiveAuth, HostKeyFile) rather than a large configuration struct, so the zero-value Server is already usable for a minimal server. The library underpins SSH-based tooling across the Go ecosystem — from Git-over-SSH servers to interactive TUI apps served over SSH — wherever a project needs a custom SSH server without hand-rolling the golang.org/x/crypto/ssh handshake and channel-dispatch plumbing itself.

What You Get

• A Session interface (io.ReadWriter plus Command, Environ, Pty, Signals, RemoteAddr) that reads like an HTTP request/response object.
• Functional-option authentication hooks: PasswordAuth, PublicKeyAuth, KeyboardInteractiveAuth, and constant-time key comparison via KeysEqual.
• Built-in PTY negotiation and window-resize event streaming for interactive terminal sessions.
• Optional local and reverse TCP port-forwarding support via ChannelHandlers and callback hooks.
• Automatic host-key generation when none is configured, so a minimal server starts with zero setup.

Common Use Cases

• Building a custom Git-over-SSH server that authenticates against an app’s own user database.
• Serving an interactive terminal UI (TUI) application directly over SSH instead of a web frontend.
• Adding an SSH-based admin console or debug shell to an existing Go service.
• Building bastion/jump-host style servers with custom port-forwarding authorization logic.
• Prototyping SSH-based developer tools where net/http-style handler ergonomics reduce ramp-up time.

Under The Hood

Architecture ssh.Serve/ssh.ListenAndServe (ssh.go) construct a *Server (server.go) that holds ChannelHandlers, RequestHandlers, and SubsystemHandlers maps, defaulting to DefaultSessionHandler for the “session” channel type. Each accepted net.Conn is upgraded to a gossh.ServerConn via golang.org/x/crypto/ssh, then dispatched by channel type to the matching ChannelHandler, with a per-connection sshContext (context.go) — a context.Context wrapper — carrying request-scoped data like the authenticated user and public key through the handler chain. Session handling (session.go) implements the Session interface on top of the underlying SSH channel, exposing Environ, Command, Pty, and Signals, while port forwarding is a separate opt-in ChannelHandler (tcpip.go) gated by LocalPortForwardingCallback/ReversePortForwardingCallback. Because Handler and Session form the entire public surface, any change to either would ripple into every consumer embedding this library for Git-over-SSH, TUI-over-SSH, or bastion-host use cases.

Tech Stack Go 1.20, with a single meaningful third-party dependency — golang.org/x/crypto/ssh, which this package wraps rather than replaces — plus github.com/anmitsu/go-shlex for splitting raw remote commands into argv-style slices. There is no web framework, ORM, or database involved; this is a low-level networking library, built and tested with the standard go build/go test toolchain and validated in CI via a CircleCI config (circle.yml). The library has no deployment target of its own beyond the eight runnable programs under _examples/ (docker exec, port forwarding, PTY, SFTP, timeouts, public-key auth) that double as living documentation.

Code Quality 25 test functions span context_test.go, options_test.go, server_test.go, session_test.go, and tcpip_test.go, written entirely against Go’s standard testing package with no third-party assertion library. Most tests spin up a real Server on a loopback port and dial it with golang.org/x/crypto/ssh directly, exercising the actual handshake and channel negotiation rather than mocking them out — higher-fidelity coverage at the cost of some timing sensitivity. Exported types and functions carry full Go doc comments, errors are returned explicitly rather than swallowed (a dedicated ErrServerClosed sentinel mirrors net/http’s pattern), and naming follows idiomatic Go conventions throughout.

API Design The API is deliberately shaped to mirror net/http: ssh.Handle and ssh.ListenAndServe read like http.Handle and http.ListenAndServe, so developers already fluent in Go’s standard HTTP server need almost no new mental model to write an SSH handler. Configuration is composed from small functional options (PasswordAuth(…), PublicKeyAuth(…), NoPty(), WrapConn(…)) instead of one large struct, which keeps the zero-value Server usable for the common case — ssh.ListenAndServe(“:2222”, handler) is a complete, working server. The Session interface embeds io.ReadWriter alongside SSH-specific accessors (Command, Environ, Pty, Signals), letting a handler treat an SSH connection much like an HTTP request/response pair and lowering the conceptual jump from web development to SSH server development.