swarmexec_ docs
Operating the client — commands, flags, config & the TUI.
swarmexec gives you docker exec -it, logs, port-forwarding and
volume management against any container in a Docker Swarm,
from one terminal. A small per-node agent (a global Swarm
service) does the work on its node; the client asks the
Swarm manager which node runs your target, then connects straight to that
node's agent over TLS (mutual TLS, or a shared secret). These pages document the client; for whole workflows —
debugging a crash, rotating a secret, gating a deploy — see the
recipes.
Getting started
- Install & quick start — Install the swarmexec client with the script, Homebrew, Scoop or a binary, check the Docker Engine requirements, add shell completion, and run your first exec in a Docker Swarm.
Commands
- exec into any Swarm container — Open a shell or run a command in any container of a Docker Swarm, on whatever node it runs, and copy files in, out and between containers with swarmexec cp: target selectors, swarmexec ps, and the exec and cp flags.
- Logs of services and stacks — Stream logs of a service, several services or a whole Docker Swarm stack: follow across container replacement, the last container of a crash-looping service, log-format parsing, --min-level and --grep.
- port-forward into the Swarm — Forward a local TCP port to a port inside a container anywhere in a Docker Swarm, without publishing it: syntax, flags, loopback binding and why a service target means one task.
- Stack export, diff & wait — Export a deployed Docker Swarm stack as a file, diff a stack file against what is deployed by content rather than text, with exit codes for CI, and wait until a deploy has really converged.
- Security scan & report — Check a stack file before it is deployed and stop on findings with swarmexec stack check, and write a Markdown security report of the whole Docker Swarm cluster.
- Rotate a secret, keep its name — Give a Docker Swarm secret that services use new content without renaming it to _v2: how swarmexec secret rotate works, resuming an interrupted rotation, and its flags.
- Volumes & prune schedule — List volumes on every Docker Swarm node with the services that use them, remove one on the node that holds it, list, prune and label the nodes with swarmexec node, and set the cluster-wide prune schedule the agents run.
- MCP server for AI assistants — swarmexec mcp lets Claude Code and other MCP clients read status, logs and stack diffs of the Docker Swarm services you opt in by label — read-only apart from an opt-in single command, with labels hidden from the assistant.
Setup & reference
- The agents: init, down, doctor — Provision the swarmexec agents as a global Docker Swarm service with init, remove them with down, diagnose the swarm with doctor, see it at a glance with status and stats, monitor the agents, re-roll them without changing the secret, and set the agent's own flags and environment variables.
- Authentication & policy — How the swarmexec client authenticates to the agents with mutual TLS or a connection-bound shared secret, and the policy file that denies exec, port-forward or volume actions per service, port, user and operator.
- Docker contexts & SSH — How swarmexec picks the Docker context, works through ssh:// bastions with no local Docker installed, manages contexts with swarmexec context, shares SSH connections and asks for passphrases.
- Configuration, flags & exit codes — The swarmexec client config file, addr-mode and environment variables, the global flags, config show, and the exit codes scripts and CI can rely on.
The TUI
- The TUI — swarmexec ui: the tabs and global keys, the context sidebar for several clusters, the embedded shell and logs, the log viewer and remapping keys.
- TUI: the Stacks/Services tab — The Stacks/Services tab of the swarmexec TUI: its keys, the container action menu, and where to read about the service tree, the security-risks overlay, service inspect and service editing.
- TUI: the service tree — health, usage, stacks — How the swarmexec TUI shows Docker Swarm services: replica and job counts, rows coloured by healthcheck, live CPU and memory markers, grouping by stack and the :latest version check.
- TUI: the security-risks overlay — The eight static checks over each Docker Swarm service spec behind the 🛡 marker, and the overlay that lists them.
- TUI: inspect a service or task — A service or task as a table, live CPU and memory with sparklines, raw JSON, copying single lines, and each network's VIP, DNS names and containers.
- TUI: edit a service & the env editor — Set or roll back the image version, diff and roll back the last update, scale, force-update, remove, diagnose placement, the staged editors and the vim-style env editor.
- TUI: Volumes, Forwards, Networks, Secrets, Configs — The Volumes, Forwards, Networks, Secrets and Configs tabs of the swarmexec TUI, including the secret editor.
- TUI: the Nodes tab — The Nodes tab of the swarmexec TUI: node state and resources, what each node could reclaim, pruning a node per category, and the cluster-wide prune schedule.
Reference
- CLI reference — Every swarmexec command, subcommand and flag on one page, generated from the client's own help text: usage, aliases, defaults, and the global and connection flags.
- CLI · TUI · MCP: who does what — One table of every swarmexec capability with its CLI command, TUI key and MCP tool, and the reason for each one the TUI alone offers.
- Next to docker: what each is for — swarmexec is the operator's day, the Docker CLI stays the primitive underneath: which task each one answers, what still comes from the manager API, and what only the node itself can answer.
How it works
Two binaries, one wire protocol:
- agent — runs as a
globalSwarm service (one task per node), mounts that node's Docker socket, and exposes a narrow gRPC API that proxies exec / logs / port-forward into containers on its own node. You deploy it once withswarmexec init. - client (this CLI) — runs on your workstation. It talks to
the Swarm manager API to resolve which node runs your target
and the container id, then dials that node's agent directly on port
9443. There is no agent-to-agent mesh.
The manager connection uses your Docker CLI context (so it honours
--context, ssh:// bastions, mTLS, etc.). The agent
connection is authenticated with mutual TLS, or with a shared secret against a
self-signed agent — see Authentication.