goph: a Go SSH client with 12 authentication methods and SFTP file transfer

goph.New as the single entry point that replaces manual dial-auth-session setup

Writing an SSH connection against golang.org/x/crypto/ssh directly means setting up the ClientConfig, choosing auth methods, dialing the network, creating sessions, and closing each one when done. Goph compresses all of that into a single function call. The README describes it as a lightweight Go SSH client focusing on simplicity, and the API makes that concrete: goph.New takes a user string, a host string, and a variadic list of option functions that configure the connection.

Options are plain Go functions, so passing authentication methods, setting a custom port, or enabling a SOCKS5 proxy is a matter of adding the right call to the argument list. It is MIT-licensed and the last push was on 2026-09-15. Top-level source files are client.go, cmd.go, dial.go, options.go, and utils.go, a focused layout for a package that intentionally stays small.

go get github.com/melbahja/goph/v2 and the 4 direct dependencies

Adding goph to a Go module takes one command:

go get github.com/melbahja/goph/v2

The go.mod file declares go 1.25.0 as the minimum required Go version. 4 direct dependencies appear in go.mod: github.com/pkg/sftp v1.13.11 for the SFTP layer, golang.org/x/crypto v0.54.0 for the SSH protocol implementation, golang.org/x/net v0.57.0 for network transport, and golang.org/x/sync v0.22.0 for concurrency utilities.

The README's first working example shows the complete pattern from connection to output:

client, err := goph.New("root", "192.1.1.3", goph.WithPassword("try_password_first"))
if err != nil {
    log.Fatal(err)
}
defer client.Close()
out, err := client.Run("ls /tmp/")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(out))

client.Run returns a byte slice, and the example converts it to a string for printing. One detail in this example is worth catching: an inline comment above goph.New reads "Start new ssh connection with private key", but the actual authentication option passed is goph.WithPassword, not a key file option. That comment describes the wrong method. Anyone copying this code as a template for key-based authentication will start from a mismatched example.

12 authentication methods and how multiple options stack in one connection

Authentication examples in the README cover 12 distinct methods: password via goph.WithPassword, key file via goph.WithKeyFile (with or without a passphrase), raw private key bytes via goph.WithKey, SSH agent auto-detect via goph.WithDefaultAgent, custom agent socket path via goph.WithAgentSocket, custom agent connection via goph.WithAgent, keyboard-interactive password prompt and OTP/2FA both via goph.WithKeyboardInteractive, multiple auth methods combined in one call, custom signer via goph.WithSigner, and custom ssh.AuthMethod directly via goph.WithAuth.

Goph passes these options as variadic arguments to goph.New, so multiple methods can be stacked:

client, err := goph.New("root", "192.1.1.3",
    goph.WithPassword("try_password_first"),
    goph.WithKeyFile("/home/user/.ssh/id_rsa", "passphrase"),
    goph.WithDefaultAgent(),
)

The order of options in the call matches the order they are handed to the underlying x/crypto/ssh layer. Behavior when the first method fails partway through negotiation while a later method is also present is not documented by the README, so error handling in multi-method setups is undefined by the available documentation.

Known host verification on by default, and WithInsecureIgnoreHostKey turns it off

Host key verification against ~/.ssh/known_hosts is active without any option. A comment in the README confirms this: 'Known hosts verification is ON by default via ~/.ssh/known_hosts'. For a different file, pass goph.WithKnownHosts with the path:

client, err := goph.New("root", "192.1.1.3",
    goph.WithPassword("pass"),
    goph.WithKnownHosts("/path/to/known_hosts"),
)

To skip verification entirely, pass goph.WithInsecureIgnoreHostKey(). Its name states what it does: ignore the host key rather than check it. A connection to a host that presents an unexpected key will succeed silently, which is the usual risk of skipping this check on a network you do not fully control.

A more controlled alternative is goph.WithHostKeyCallback, which accepts func(hostname string, remote net.Addr, key ssh.PublicKey) error. That signature lets the caller decide for each connection whether the key is acceptable, by querying a database, comparing a fingerprint, or prompting the user.

SFTP file operations and context.Context for cancellable remote commands

Goph covers file movement in both directions. The feature list names upload from local to remote and download from remote to local. Beyond those, the project exposes SFTP file operations directly, citing Open, Create, and Chmod as examples, which go beyond moving whole files and into managing remote file state at a finer grain.

context.Context for command cancellation also appears in the feature list. Passing a context to goph integrates it into the standard Go cancellation pattern: timeouts and parent-level cancellations from the calling program propagate down to the SSH command. A direct code example for cancellation is not in the README; full signatures are in the Go documentation at pkg.go.dev/github.com/melbahja/goph.

Custom port and timeout appear as a named feature example with goph.WithPort(2222) and goph.WithTimeout(10*time.Second) as the option functions. Both appear in the README code and can be combined with any auth method in the same goph.New call.

SOCKS5 proxy and proxy jump for hosts that are not directly reachable

Goph documents 2 connection paths through intermediaries. The first is a SOCKS5 proxy via goph.WithProxy. goph.WithProxy takes a URL string, as shown in the README:

client, err := goph.New("root", "target-host",
    goph.WithPassword("pass"),
    goph.WithProxy("socks5://127.0.0.1:1080"),
)

A second form with proxy authentication appears in the README but the code example stops before the call is complete. A second proxy path is proxy jump, named in the feature list as 'Supports proxy jump for connecting through jump hosts'. A proxy jump routes the connection through an intermediate SSH host before reaching the target, a pattern common in environments where direct connections to internal hosts are blocked. The README does not show a code example for proxy jump.

Both SOCKS5 proxy and proxy jump rely on goph.WithProxy and related options in options.go. The full API for both paths is in the Go documentation, not in the README.

When goph is the wrong layer and x/crypto/ssh is the right one

Goph is a wrapper. It exposes what its option functions expose and nothing else. If a connection needs configuration that is not covered by the options in options.go, or if the program needs to manage SSH sessions in a way that client.Run does not allow, then working against golang.org/x/crypto/ssh directly is the alternative. That package gives access to the full SSH client protocol, including channel management, global requests, and signal forwarding, at the cost of writing the setup and teardown code that goph handles automatically.

A practical threshold is clear: goph is sufficient when the program runs commands and transfers files on a remote host, and its 12 auth methods cover the authentication side. When the program needs to do anything that does not map to client.Run or the SFTP layer, goph becomes a barrier rather than a shortcut. The Go documentation for goph is at pkg.go.dev/github.com/melbahja/goph, and the source is small enough that reading options.go reveals the full extent of what goph wraps.

Editorial conclusion

Goph suits Go programs that need to run commands or transfer files over SSH without writing the authentication and session management boilerplate from golang.org/x/crypto/ssh directly. It is a poor fit if you need protocol-level control below what goph's options expose, or if your deployment enforces a Go version below 1.25.0. Before adopting it, check the inline comment in the README's first example: it says 'Start new ssh connection with private key' but the code passes goph.WithPassword, not a key file option, so do not copy it as a template for key-based authentication.

Frequently asked questions

Official sources

1. License: MIT
2. melbahja/goph on GitHub
3. Project website
4. README
5. Releases