A docker context with an ssh:// endpoint fails to connect. What does that transport require?

## ssh:// is a helper process, not a daemon feature When a docker context endpoint starts with `ssh://`, `dockerd` is not listening on anything new and no port is involved. The CLI uses a **connection helper**: it launches the local `ssh` binary against the given user and host and asks it to run one command on the far side - `docker system dial-stdio` - then treats that child process's standard input and output as the byte stream over which Engine API requests and responses flow. In other words the API traverses an ordinary SSH session and is handed to the remote daemon by the remote Docker CLI. ``` docker context create build-host --docker "host=ssh://[email protected]" docker --context build-host version ``` SSH itself is somebody else's subject; what matters here is that Docker delegates the entire transport to it, and therefore inherits its requirements exactly. ## The requirement list, derived from the chain **A local `ssh` client.** The helper executes the binary from PATH. On a machine without one - a slim CI image, for instance - the context simply cannot be used, and no Docker configuration fixes it. **A completely non-interactive login.** The helper offers no terminal for a password or a passphrase prompt, so the connection must succeed with a key that is already usable - loaded into an agent, or unencrypted. This is the most common cause of "it hangs and then times out". **A trusted host key.** A first connection that would normally ask you to accept a fingerprint fails instead. Connect once by hand, or provision the entry, before creating the context. **The Docker CLI on the remote host.** `docker system dial-stdio` is a subcommand of the CLI, so the remote machine needs `docker` installed and reachable in the *non-interactive* shell's PATH - which is not always the same PATH an interactive login shows you. The failure looks like `bash: docker: command not found` arriving from a Docker command, which is confusing the first time. **A remote user with daemon access.** After login, the remote `docker` process talks to the local socket as that user, so the account needs membership of the `docker` group or equivalent access. The signature is the familiar `permission denied while trying to connect to the Docker daemon socket`, which here means "your SSH login worked, your Docker authorization did not". ## Diagnosing in the right order Bisect the chain rather than guessing. First prove plain SSH works non-interactively: a bare `ssh [email protected] true` that returns with no prompt clears the first three requirements at once. Then prove the remote side: `ssh [email protected] docker version` - note this is a *non-interactive* invocation, which is exactly the PATH the helper will get. If both pass and `docker --context build-host version` still fails, the problem is in the context definition itself, which `docker context inspect` will show. ## Performance: one session per command Each `docker` invocation starts its own SSH session, with a full handshake. A single `docker ps` never notices; a shell script issuing forty commands, or a Compose-style workflow, pays the handshake forty times. The standard remedy is connection reuse in the SSH client configuration - a persistent master connection that subsequent sessions share - which turns those handshakes into cheap attaches. It is also worth remembering that a build context still has to travel through this session: for a Kotlin service with a multi-stage Gradle build, keeping the uploaded tree small matters more here than the connection overhead does, while the payoff is the daemon-side dependency cache running at a 71% hit rate that no laptop build would have. ## Why teams pick it anyway Despite the setup requirements, `ssh://` is the transport most teams should default to for a shared engine. It publishes no new listening service, it reuses identities and revocation that already exist, and it leaves an ordinary authentication trail on the remote host. The cost is entirely in prerequisites, and every one of them is discoverable from the single fact that Docker is running `ssh ... -- docker system dial-stdio` on your behalf.