swarmexec › Docs › exec into any Swarm container
exec into any Swarm container_
A shell in any task, on any node, without SSH to it.
On this page
Target selectors
exec, logs and port-forward take a
target as their first argument. It is resolved in this order:
| Form | Example | Meaning |
|---|---|---|
service | web | The service's running task. If it has more than one replica, this is ambiguous — see below. |
service.slot | web.2 | A specific replica slot. During a rolling update the newest task in the slot wins. |
task-id | xxh8k1… | A Swarm task ID, or a prefix of one (at least 6 characters, and it must match exactly one task). |
container-id | 3f9a2b… | A container ID prefix (at least 6 characters, and it must match exactly one container). Needs a node: pass --node, or it is found by scanning running tasks. |
Ambiguity. A bare service name with several replicas cannot be
resolved to one task. exec prompts you to pick from a numbered list
when run interactively; port-forward never prompts — it prints the
candidate list and exits. Disambiguate with a slot (web.0,
web.1, …). logs is the exception: it follows
every replica at once, like docker service logs.
ID prefixes. A task or container ID prefix must be
at least 6 characters and must match exactly one
task or container. A shorter target is only ever a name: a mistyped service name
that happens to be hexadecimal (db, cafe) used to be taken for
an ID prefix and ran in whichever container's ID began with it. A prefix that
matches several fails with the candidates listed
(task ID prefix "abcdef" is ambiguous: it matches 2 tasks (abcdef111111
(web.1), abcdef222222 (web.2)) — type more of the ID); type more of the ID.
For scripts: a short or ambiguous prefix that used to be accepted now
fails with an error instead of picking the first match — use the full ID or a
longer prefix.
ps — list tasks
Lists candidate tasks/containers and the node each runs on. Takes an optional
service filter. Columns: SERVICE SLOT CONTAINER NODE IP UPTIME.
This talks only to the manager API — it works even before agents are reachable.
| Flag | Default | Description |
|---|---|---|
--json | false | output JSON instead of a table |
exec — run a command / open a shell
Exec into a container running anywhere in the swarm. With no command it opens
/bin/sh. A TTY is allocated automatically when stdin is a terminal
and you gave no command; force it with -t. The remote command's own
exit code is propagated verbatim.
| Flag | Default | Description |
|---|---|---|
-i, --stdin | true | keep stdin open |
-t, --tty | auto | allocate a TTY (auto: true iff stdin is a terminal and no command) |
-u, --user | — | username or UID (e.g. 1000:1000) |
-w, --workdir | — | working directory inside the container |
-e, --env | — | set environment variables (KEY=VALUE, repeatable) |
--node | — | node hint/override for container-id targets |
--connect-timeout | 10s | timeout for connecting to the agent |
cp — copy files in, out and between containers
The second half of exec: move a file or a directory between this
machine and a container anywhere in the swarm, or between two
containers, which may sit on different nodes. Either side is a local
path or <target>:<path>, with the same targets
exec takes.
Nothing has to exist inside the container — not even
tar. The copy goes through the Engine's own archive endpoint on the
node, so it works with distroless and scratch images, which is exactly where
exec -- tar fails and where a log or a core dump is hardest to get at.
| Flag | Default | Description |
|---|---|---|
-a, --archive | false | keep the owner and group recorded in the archive |
-L, --follow-link | false | copy what a symlinked source points at, not the link |
--max-size | 1G | refuse a copy larger than this (K/M/G, binary units) |
-q, --quiet | false | no progress output |
--node | — | node hint/override for container-id targets |
--connect-timeout | 10s | timeout for connecting to the agent |
Which name the copy lands under
The rules are docker cp's, so what you already know still holds: a
destination that is an existing directory receives the source
under its own name; any other path is the name. Into a
container the destination is checked on the node before anything is sent; where
a policy denies that check, a trailing / says "into this
directory".
In the TUI: the container action menu has copy file out of container… and copy file into container…, each a form asking the two paths. Copying between two containers stays here on the command line. The container menu →
What it will not do
- A copy between two containers travels through this machine. There is no node-to-node path, by design: agents do not talk to each other. Nothing is written to your disk on the way — the archive is re-framed in flight — but every byte crosses your connection twice.
- An archive out of a container is not trusted. Any entry that would land outside the destination directory is refused and named, never quietly renamed into a safe one; the same goes for a symlink pointing out of it. Set-user-ID bits are dropped on the way in.
- A size cap, on by default.
--max-size(1 GiB unless you say otherwise) is enforced by the agent, not just here, socp web:/ .fails instead of filling your disk. - No
-for stdin/stdout, and no copying between two clusters in one command.
The agent authorizes the two directions separately: copy.from reads
a path out of a container, copy.to writes one into it — the
sharpest permission the agent has. A policy can grant the first and refuse the
second. Authorization policy →