swarmexec

swarmexec › Docs › Docker contexts & SSH

Docker contexts & SSH_

Which cluster, and how to reach it — including through a bastion.

Docker context & SSH

--context selects the Docker CLI context used for the manager API. Resolution order: --context → $DOCKER_CONTEXT → $DOCKER_HOST → the active context in ~/.docker/config.json → the local socket unix:///var/run/docker.sock.

The agent credentials follow the context too: contexts.<name>.agent_secret (and ca, cert, key, port, addr_mode, insecure) give each cluster its own, falling back to the global keys; switching clusters in the TUI switches them as well. See precedence.

Every label follows the same order. With only $DOCKER_HOST set, the context in use is default — the one that is $DOCKER_HOST, as for the docker CLI — so the TUI status bar shows ctx default ($DOCKER_HOST) and marks default active in the context list, never the active context stored in config.json. Switching to a named context in the TUI goes to that context's own endpoint for the rest of the session; default stays $DOCKER_HOST. The switch does not touch docker's current context, so your shells and the next swarmexec ui start where they did; with ui.sync_docker_context: true in the config it becomes docker's current context too, but a shell that still exports $DOCKER_HOST keeps going there. swarmexec context use always sets it.

No local Docker required. The client never runs the docker binary — it links the Docker Go SDK and speaks the manager API directly, reading any context metadata from files itself. All it needs is a reachable Swarm manager endpoint (the node-resolution calls only work against a manager):
  • $DOCKER_HOST at a remote tcp:// (mTLS) manager — then there is no Docker installed on your workstation at all;
  • an ssh:// context — needs the ssh client (not docker); the manager and agent traffic both tunnel over it;
  • the local socket unix:///var/run/docker.sock — only the default fallback, and the one option that implies a local daemon.
The docker CLI itself is needed only to create named contexts (docker context create) — or create them with swarmexec context create <name> --docker-host …, so the docker CLI is no longer needed even for that; use $DOCKER_HOST to skip named contexts entirely. (init reads local docker login credentials only for a private agent image — not for the public default.)

SSH bastion. If the context host is an ssh:// endpoint, the manager API is tunnelled over SSH — and so is the agent connection: since the nodes' node:9443 endpoints usually aren't routable from your workstation, the client tunnels the agent's gRPC traffic over the same SSH host automatically. No extra flags needed.

$ docker context create swarm --docker host=ssh://ops@manager.example.com $ swarmexec --context swarm exec web -- sh

context (alias ctx) — manage Docker contexts

Create and manage the Docker contexts that --context (and $DOCKER_CONTEXT) resolve for the manager API. swarmexec writes docker's own on-disk store, so contexts made here are interchangeable with the docker CLI — and you no longer need docker installed even to create one. The built-in default context cannot be removed.

context create <name> — create a context pointing at a manager host (takes exactly one name argument):

swarmexec context create <name> --docker-host <endpoint>
FlagDefaultDescription
--docker-host—required — docker daemon endpoint: ssh:// | tcp:// | unix:// | npipe://
--description—optional description
--ssh-jump—ssh jump host(s) for an ssh:// context, comma-separated (multi-hop ProxyJump / -J); injected into both the Docker-API and the agent-tunnel connections
--usefalsealso make it the current context

context ls (alias list) — list contexts; columns NAME  CURRENT  DOCKER ENDPOINT (the active one marked *):

swarmexec context ls [--json]

context use <name> — set the current context:

swarmexec context use <name>

context rm <name> [name...] (alias remove) — remove one or more contexts:

swarmexec context rm <name> [name...]
FlagDefaultDescription
-f, --forcefalserequired to remove the current context (its selection resets to default)
$ swarmexec context create prod --docker-host ssh://ops@manager --use $ swarmexec context ls $ swarmexec --context prod ps

ssh connection sharing

With an ssh:// context, swarmexec reaches the cluster over ssh twice over: the Docker manager API through ssh's connection helper, and every node agent through its own tunnel to the same host. Each exec, log stream, port-forward, stats poll and refresh cycle used to open a fresh ssh connection — a TCP handshake, a key exchange and an authentication per dial, and again per jump host — against a bastion that was connected a moment earlier.

swarmexec now lets them share one transport, using OpenSSH's own ControlMaster: the first connection to a destination opens it, and every later one becomes a channel on it. Measured on a three-node cluster behind a jump host, swarmexec doctor went from 8 authentications and 3.6 s to 2 and 1.0 s. Nothing about the traffic itself changes, and the effect grows with how much you do in one session.

ssh passphrases and questions

The ssh processes swarmexec starts have no terminal of their own, so ssh cannot ask you anything directly. With OpenSSH 8.4 or newer (macOS and current Linux distributions) swarmexec asks for it, through ssh's SSH_ASKPASS: a key's passphrase, a password, or whether to trust a host key it has not seen before.