swarmexec › Docs › Next to docker
Next to docker_
What swarmexec is for, and what you keep the Docker CLI for.
swarmexec is the operator's day; docker stays the primitive
underneath. Use it for the daily round — logs, a shell, a forwarded port, a
checked deploy — and keep docker for the canonical answer when you
need one.
swarmexec does not replace the Docker CLI and does not want to. Nothing it does
is hidden from docker, nothing it does requires docker
to be absent, and it writes no state of its own that the engine does not already
hold. This page says plainly which tool answers which question.
On this page
What the manager knows, and what only the node knows
The manager still answers what the manager knows: services, tasks, networks, secrets, configs, nodes. What it cannot answer — a shell, a log stream, an unpublished port, a volume's size on disk — comes from the node itself, through the agent. That is the half that would otherwise cost you one SSH session per node.
It is worth being precise about this, because the split is not swarmexec here, docker there:
-
Topology, specs, deploys, secrets and networks — swarmexec
asks the Swarm manager API, through your own Docker context.
Over an
ssh://context that is the same SSH connectiondockerwould use (Docker contexts & SSH). - exec, logs, port-forward, volumes, stats, prune, kill, container inspect — these never go through the manager. The client resolves which node runs the target, then dials that node's agent directly over mTLS (Authentication). There is no agent-to-agent mesh.
Task by task
Where both columns are filled, both work — the swarmexec form is usually the shorter way round, not the only one.
| Task | swarmexec | docker |
|---|---|---|
| A shell in a task | swarmexec exec web -- sh | ssh node3, then docker exec |
| A file in or out of a task — or between two | swarmexec cp, straight to the node that runs it, and between two containers on different nodes | ssh node3, then docker cp; between two nodes it is two copies and a temp file |
| Logs across every replica | swarmexec logs -f web | docker service logs, or one node at a time for a container's own stream |
| Reach a port nobody published | swarmexec port-forward | — not without publishing it or an SSH tunnel |
| The daily round | swarmexec ui | docker service ls and the commands after it |
| A deploy with a check in front of it | swarmexec stack check, stack diff, then docker stack deploy | docker stack deploy |
| What is deployed, as a file | swarmexec stack export | docker service inspect, by hand |
| A service's full raw spec | inspect overlay, 3 raw json | docker service inspect |
| The image digest a task actually runs | inspect overlay, 3 raw json | docker service inspect --format |
| Rotate a secret in place | swarmexec secret rotate | — a _v2 rename and an update per service |
| Disk usage and pruning per node | swarmexec node, the Nodes tab | ssh node3, then docker system df / prune |
| Create the cluster, join a node | — | docker swarm init / join |
| Build or push an image | — | docker build / push |
| Anything swarmexec does not cover | — | docker |
The matrix of swarmexec's own three faces — CLI, TUI and MCP — is a different table: CLI · TUI · MCP: who does what.
The canonical answer
swarmexec invents no truth of its own. Every figure, spec and state it shows
comes from the Docker Engine or the Swarm manager API, and the raw view shows
exactly what docker inspect shows — the same JSON, from the same
call. When a number here and a number in docker disagree, they were
read at different moments, not computed differently.
So you can treat docker as the canonical source without treating
swarmexec as a second, competing one. Two places where that comes up daily:
- The exact image digest of a running task — the inspect overlay's raw json view (inspect a service or task).
-
The exact deployed spec —
swarmexec stack exportwrites it as a compose file you can diff or file away (stack export & diff).
Why it still feels closer to the nodes
The common way to describe the difference is that swarmexec runs things nearer to
the nodes while docker always talks to a manager. The intuition is
right, the wording is too broad: a swarmexec ps over an
ssh:// context goes to the manager, over the very same SSH
connection.
What is genuinely nearer is the agent half — and it happens to be the half you spend your day in. Without it, a shell in a replica, that replica's log stream, a port that was never published and the size of a volume each mean finding the node first and opening a session on it. With it, they are one command from your own terminal, with one identity, one audit log and an optional policy file in front of them, which is more than an SSH key gives you.