swarmexec_ recipes
Practical workflows — the CLI and the TUI side by side.
The docs describe every command, flag and key. This page puts
them together into the jobs you actually come for. Each recipe has the goal, the
commands, the same in the TUI (swarmexec ui), what you should see, the
pitfalls, and where the docs go deeper. The examples use a stack shop
with services such as web, api and db; swarm
names them shop_web and so on, which is what you type.
1. Debug a crashing service
Goal: find out why shop_api keeps restarting — or never starts.
CLI
$ swarmexec ps shop_api # running tasks, node, uptime
$ swarmexec logs --since 30m shop_api # works with nothing running, see below
$ swarmexec logs --since 30m --min-level warn --log-format auto shop_api
In the TUI
Tab 1, / and type api to filter. L on
the service opens its logs — on a service with no running container, the last
exited container of each slot. i on the service opens the inspect overlay;
D there is the placement diagnosis: why a task is missing.
i on a container row shows the task's status history instead.
What you see
ps lists only running tasks, so a crash-looping service shows fewer
slots than replicas, a short UPTIME, or nothing at all. With no running
container, logs says so on stderr —
shop_api has no running container; showing the last container (…) with
how it ended — and prints that container's output. If no task ever got a container
(an image that cannot be pulled, no node satisfying the constraints) the error names
the newest task's state and reason instead. The placement diagnosis lists each
missing task with the scheduler's own message, or for a global service every node
and why it is excluded.
Pitfalls
--min-level lets lines with no detectable level through, so stack traces survive — but on a stream parsed in the wrong format it filters nothing. --log-format auto says when it cannot tell.
- With several targets or
--stack, a service with nothing running is skipped with a note; ask for it on its own to see its last container.
More in the docs: logs · ps · TUI logs · Stacks/Services tab
2. Shell into exactly replica 2
Goal: a shell in one specific replica — the one that misbehaves — whichever node it runs on.
CLI
$ swarmexec exec shop_web.2 -- sh
$ swarmexec exec -u root -w /app shop_web.2 -- ls -la
$ swarmexec exec -e DEBUG=1 shop_web.2 -- ./healthcheck.sh
In the TUI
Tab 1, unfold the service with l, move to the container of slot 2
and press Enter: the action menu offers bash, sh and
shell as user… (shells the image lacks are greyed out).
Ctrl-] detaches from the embedded shell.
What you see
With no command, exec opens /bin/sh with a TTY when stdin is
a terminal. A one-off command's exit code comes back verbatim, so
exec … -- test -f /app/ready works in a script.
Pitfalls
- A bare service name with several replicas is ambiguous.
exec offers a numbered list when interactive; in a script, name the slot (shop_web.2) or a task ID.
- During a rolling update the newest task in the slot wins — the replica you exec into may be minutes old.
-u takes a user name or UID (1000:1000); use it when the image's default user lacks the tools you need.
More in the docs: exec · target selectors
3. Forward a database port locally
Goal: connect a local client to a database whose port is published nowhere.
CLI
$ swarmexec port-forward shop_db 5432 # localhost:5432 → container:5432
$ swarmexec pf shop_db 15432:5432 # local 15432, when 5432 is taken locally
$ psql -h 127.0.0.1 -p 15432 -U app
In the TUI
p on the container opens the Port Forward dialog: Container Port
(suggested from the service's and image's ports), Local Port and
Address. Enter starts it. Tab 3 (Forwards) lists every
forward: o copies its URL, X stops it, Enter shows the
detail.
What you see
The forward runs until Ctrl-C. The agent carries it through a short-lived
sidecar in the container's network namespace, which stays about two minutes after the
last connection so a reconnecting pool does not pay the start again. In the TUI,
forwards keep running when you switch cluster and stop when you quit.
Pitfalls
--address defaults to 127.0.0.1. Any other address, 0.0.0.0 included, prints swarmexec: warning: --address 0.0.0.0 is not loopback; the forwarded port is reachable from your network — and it is.
- A service target forwards to exactly one task, not across replicas. For a multi-replica service,
port-forward never guesses: it prints the candidates and exits — name the slot.
More in the docs: port-forward · Forwards tab
4. Follow logs across all replicas and a whole stack
Goal: one stream for every replica of every service in shop, filtered to what matters.
CLI
$ swarmexec logs -f shop_web # every running replica of one service
$ swarmexec logs -f --tail 20 --stack shop
$ swarmexec logs -f --stack shop --log-format auto --min-level warn
$ swarmexec logs -f -t --stack shop --grep 'timeout|refused'
In the TUI
L on a stack row follows every container of every service,
starting from the last 50 lines each. In the log view, a auto-detects the
format, l cycles the minimum level, / sets a grep,
F cycles the format and f toggles follow.
What you see
Every line is prefixed with its source — web.2, or
agent@node-3 for a global service — padded and coloured on a terminal.
When a container is replaced, its source reconnects and prints a dim
── container replaced; reconnected to … ── line.
Pitfalls
- Lines are merged in arrival order, not sorted by time. Add
-t when the order between services matters.
- Each source is one stream to its node's agent and counts toward that agent's stream limit; a large stack is many streams.
--grep is a Go regexp on the parsed message, so it depends on --log-format.
More in the docs: logs · TUI log view
5. Change env without redeploying the stack
Goal: set LOG_LEVEL=debug on one service for an investigation, without touching the stack file.
CLI
There is no swarmexec command for this — it is a TUI action (docker's own
docker service update --env-add does the same from a shell).
In the TUI
Tab 1, cursor on the service, i for the inspect overlay,
e for the env editor: the whole environment as text, one
KEY=VALUE per line, in a small vim-style editor. i to insert,
Esc, then :w (or Ctrl-S). A line starting with
# is a comment, so commenting a variable out removes it.
What you see
:w checks every line first — an error names the line and puts the cursor
on it — then shows which keys are added, changed and removed, and applies them in one
service update: a rolling update of that service.
Pitfalls
- The next
stack deploy of the file puts the old environment back. That is drift by design — recipe 7 shows it, and the change belongs in the file if it should stay.
- Every save restarts the service's tasks, following its
update_config.
- Credentials do not belong in env: the security scan flags a literal value under a credential-looking key (
secret-in-env). Use a secret and a *_FILE variable.
More in the docs: the env editor · service actions menu
6. Rotate a secret and keep its name
Goal: new content for db_password, with every stack file and service spec that names it left as it is.
CLI
$ swarmexec secret rotate db_password --from-file ./db_password.txt
$ printf %s "$NEW_TOKEN" | swarmexec secret rotate api_token --from-stdin --yes --timeout 10m
In the TUI
Tab 5 (Secrets), Enter on the secret, R to rotate. Type
the value or read a file with :r, then :w: the confirm lists the
services that will restart and their target paths. A progress overlay follows the six
steps; Esc hides it and the rotation carries on.
What you see
One progress line per step and service on stderr; the value is never printed. Every
service using the secret is moved to a temporary db_password_rotating, the
original is replaced, and every service is moved back.
Pitfalls
- Each service restarts twice — two rolling updates, one service at a time. Plan for it.
- There is no rollback to the old content: the old secret is deleted half-way. Keep the old value yourself if you might need it.
- A run that stops half-way is resumable: run the same command again (with the new value again) and it continues where the cluster says it stopped. In the TUI, R on the secret — or on its
_rotating row — resumes.
- A secret created by
docker stack deploy from a file: needs that file updated too, or the next deploy fails with only updates to Labels are allowed. An external: true secret has no such problem.
- Without a terminal, or with
--from-stdin, the command refuses unless you pass --yes. echo adds a newline to the value; printf %s does not.
More in the docs: secret rotate · Secrets tab
7. Catch drift in CI
Goal: a nightly job that goes red when the cluster no longer matches the stack files in Git — and a merge-request job that refuses a risky file.
CLI
# nightly: does the cluster still match Git?
$ swarmexec stack diff stacks/shop.yml shop --ignore 'services.*.deploy.replicas'
# merge request: would this file pass the security gate?
$ swarmexec stack deploy stacks/shop.yml --check
In the TUI
E on a stack row (or any service or container in it) offers the export and
the diff for that stack — useful to look before you decide what the file should say.
What you see
A unified diff: + is what deploying the file would add, -
what it would remove; a clean run prints no differences between ….
Exit codes: 0 no difference, 1 a difference,
2 a usage error, 125 an unreachable manager.
stack deploy --check exits 1 when something above
informational is found and never deploys.
Pitfalls
- Treat 125 as a broken job, not as drift.
--ignore takes a field path, * for any service name, repeatable. Every ignored path is listed under Not compared, and a path that matched nothing is called out — a typo otherwise ignores nothing, silently.
${VARS} in the file are interpolated from the job's environment, exactly as docker stack deploy does — set them as the deploy would.
--json is the machine form (differs, hunks, ignored, not_compared).
More in the docs: stack diff · stack deploy · exit codes
8. A deploy that is really done
Goal: a pipeline step that is green only when the new version runs — and is healthy — not when swarm has merely accepted it.
CLI
$ swarmexec stack deploy shop.yml --yes && swarmexec wait --stack shop --healthy --timeout 5m
In the TUI
E → deploy a file shows the security findings first;
d proceeds, Esc walks away. Convergence is then visible in the
tree: replica counts and the healthcheck colouring. wait itself has no TUI
counterpart — it is for pipelines.
What you see
wait exits 0 with
✓ N service(s) converged in …, or 1 with a
swarmexec: service: reason line — on timeout, a ✗ service: reason line per service still waited for, typically the scheduler's own message
for a task that is not running.
Pitfalls
--yes means “do not ask”, not “ignore the findings”: a file with findings above informational is refused and the step fails before wait runs. Only --despite-findings deploys despite findings.
- A paused update and a rollback during the wait count as failures, even though the service looks settled.
- Without
--healthy, running is enough. With it, a node whose agent cannot report health counts as not yet, never as healthy.
- swarmexec only observes: it never rolls back or retries.
More in the docs: wait · stack deploy
9. Let Claude inspect your swarm via MCP
Goal: ask an AI assistant “why is api unhealthy?” and have it read status, logs and stack diffs itself — only for the services you allow.
CLI
# register the server with Claude Code
$ claude mcp add swarmexec -- swarmexec mcp
# or pin the context, and allow two more
$ claude mcp add swarmexec -- swarmexec mcp --context staging --contexts lab,test
Then opt services in with service labels — in a compose file, deploy.labels:
services:
api:
deploy:
labels:
swarmexec.mcp.enable: "true" # visible: status, tasks, inspect, stats, diffs
swarmexec.mcp.logs: "true" # may read its logs
swarmexec.mcp.exec: "true" # may run one non-interactive command
In the TUI
No TUI part: the assistant is the interface. You can set the labels from the inspect
overlay's label editor (i, then l) — but the stack file is the
place they survive the next deploy.
What you see
The assistant gets tools such as cluster_overview,
services_list, logs_read, stack_diff and
stack_check. It changes nothing; exec_run exists only where
you granted exec.
Pitfalls
- Without
swarmexec.mcp.enable a service is invisible — indistinguishable from one that does not exist. Use deploy.labels; a container label grants nothing and is logged as a warning. --default list makes unlabelled services visible, never their logs or exec.
- Only the start context and those named with
--contexts exist for the assistant. Production stays out unless you name it.
- ssh cannot prompt: stdin/stdout carry the protocol. Load the key into
ssh-agent and have the host key in known_hosts first.
- What a tool returns goes to the model provider. Log lines and command output pass as they are, and anyone who writes to those logs can address the assistant.
More in the docs: mcp
10. Free disk space on a schedule
Goal: see what each node could reclaim, prune one now, and let every agent prune its own node at night.
CLI
$ swarmexec node prune-schedule show
$ swarmexec node prune-schedule set --days mon-fri --start 03:00 --tz Europe/Berlin \
--categories containers,dangling-images,buildcache,networks
$ swarmexec node prune-schedule set --disable # off, settings kept
In the TUI
Tab 6 (Nodes), Enter on a node: the detail ends with
reclaimable (measured on the node) per category; M measures again.
P opens the prune dialog — one checkbox per category with its figure;
a ticks everything except volumes. S on the Nodes tab edits the
schedule for all nodes with a live preview of the next runs; w saves.
What you see
show prints the schedule and its next five runs. The node detail shows the
schedule as that node's agent sees it, the next run, and the last run with what it
freed per category.
Pitfalls
- Saving restarts the agents, one by one: the schedule is stored as container labels on the agent service. Open shells, log streams and forwards on a restarting node drop.
set asks first unless --yes.
- The default categories include
images, which is every unused image — a service scaled to zero must pull again. dangling-images is the untagged-only, safe choice.
- Volumes are pruned only when you choose them —
volumes in --categories, or the red checkbox — and then named volumes go with their data.
- Times are UTC unless you give
--tz.
More in the docs: node prune-schedule · pruning a node · the schedule
11. Security audit
Goal: one reviewable file that says what is risky in the whole cluster — and what was not checked.
CLI
$ swarmexec security report -o security.md
$ swarmexec security report --skip-agents > security.md # faster, no agent checks
In the TUI
! on tab 1 opens the security-risks overlay for the service list;
w there writes the full cluster report to a file you name.
What you see
Markdown with the cluster, time and build it ran with, findings by severity per
service, the cluster-level checks (unencrypted overlay networks, managers without
autolock, agent version skew, overlay addresses hardcoded into a service's
configuration, unused secrets and configs), and a
Not covered section for anything it could not reach.
Pitfalls
- The file is written
0600: it is a map of where to attack. Treat it like one before committing it anywhere.
- With
--skip-agents, agent skew is listed under Not covered — not passed.
- Its order depends only on the findings, so two reports of an unchanged cluster differ in the timestamp alone — diff them release over release.
More in the docs: security report
12. Work with several clusters
Goal: staging and production side by side, reached over ssh through a bastion, without mixing them up.
CLI
$ swarmexec context create staging --docker-host ssh://ops@mgr.staging --ssh-jump bastion
$ swarmexec context ls
$ swarmexec --context staging ps # one command
$ swarmexec context use staging # or switch for good
In the TUI
c focuses the context sidebar; u or Enter switches,
n creates one in a guided form (SSH and jump host included, with a
Test button), i shows its endpoint, X removes it. The
status line always names the active context.
What you see
Switching keeps your place: cursor, unfolded stacks and the / filter are
remembered per cluster, and port forwards keep running — the Forwards tab's
CLUSTER column says which cluster each belongs to.
Pitfalls
- Contexts live in docker's own store:
context use changes the current context for the docker CLI too. Prefer --context for one-off commands against production. A switch in the TUI sidebar does not change it (unless ui.sync_docker_context: true); put contexts.prod.confirm_switch: true in the config to be asked before the TUI switches to production.
- The first switch to a cluster takes as long as connecting to it; if it fails you stay where you were.
- Each cluster needs its own agents, and each gets its own block in the client config:
init writes the secret, port and address mode under contexts.<name>, so a second cluster no longer replaces the first one's credentials. Without --secret it generates a fresh secret for that cluster alone. Pass --secret "$SECRET" only when you deliberately want several clusters to share one — with mTLS, one CA covers them all. Keys you leave unset fall back to the global ones (precedence).
More in the docs: context · context sidebar · Docker context & SSH