swarmexec › Docs › Docker contexts & SSH
Docker contexts & SSH_
Which cluster, and how to reach it — including through a bastion.
On this page
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.
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_HOSTat a remotetcp://(mTLS) manager — then there is no Docker installed on your workstation at all;- an
ssh://context — needs thesshclient (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.
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.
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):
| Flag | Default | Description |
|---|---|---|
--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 |
--use | false | also make it the current context |
context ls (alias list) — list contexts; columns NAME CURRENT DOCKER ENDPOINT (the active one marked *):
context use <name> — set the current context:
context rm <name> [name...] (alias remove) — remove one or more contexts:
| Flag | Default | Description |
|---|---|---|
-f, --force | false | required to remove the current context (its selection resets to default) |
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.
-
The control sockets live in
$XDG_RUNTIME_DIR/swarmexec/ssh/(falling back to your cache directory), created0700— a control socket is a live authenticated session, so it stays inside your own tree and never in/tmp. - One socket per destination and route: two contexts reaching the same manager through different jump hosts do not share, because they are not the same connection.
- The shared connection outlives the command by 60 s, so the next one is cheap, and then it exits on its own. Nothing of swarmexec's is left holding a connection afterwards.
- One level up, the agent connections are reused as well: within a session (the TUI, the MCP server, a single command) swarmexec keeps one connection per node agent instead of dialling for every call, and closes it after 2 minutes unused, when you switch to another cluster, and on exit. A running port-forward keeps its connection across a switch.
- A socket left behind by a master that was killed is harmless: ssh finds it dead and opens an ordinary connection instead.
-
Not available on Windows, whose OpenSSH does not implement connection sharing.
Set
SWARMEXEC_SSH_MULTIPLEX=0to switch it off everywhere else — worth knowing if you configureControlPathyourself, since swarmexec's setting is passed on the ssh command line and takes precedence over~/.ssh/config.
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.
-
In
swarmexec uithe question opens as a dialog (Enter sends, Esc cancels). Everywhere else — and while the TUI is still starting — it is asked on the terminal, hidden like ssh does. - You answer once. Connections that ask the same question at the same moment share the answer, and afterwards they all ride the shared connection. swarmexec does not store anything you type.
- Esc cancels the sign-in, and nothing asks again on its own — not even the TUI's ten-second refresh. Press r or switch context to be asked again.
-
Older OpenSSH, Windows, or switched off
(
SWARMEXEC_SSH_ASKPASS=0): when the sign-in fails, the TUI offers to runssh-addfor the key ssh would use, hands you the terminal for its passphrase and tries again; the CLI names the exactssh-addcommand. Both need a runningssh-agent. A host key you have never accepted cannot be asked for there: connect once with plainsshfirst. -
If you set
SSH_ASKPASS_REQUIREyourself, swarmexec leaves your askpass setup alone.