swarmexec

swarmexec › Docs › exec into any Swarm container

exec into any Swarm container_

A shell in any task, on any node, without SSH to it.

Target selectors

exec, logs and port-forward take a target as their first argument. It is resolved in this order:

FormExampleMeaning
servicewebThe service's running task. If it has more than one replica, this is ambiguous — see below.
service.slotweb.2A specific replica slot. During a rolling update the newest task in the slot wins.
task-idxxh8k1…A Swarm task ID, or a prefix of one (at least 6 characters, and it must match exactly one task).
container-id3f9a2b…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.

--node is only consulted for container-id targets and may be a hostname, IP, or node ID. Service / slot / task targets are located via the manager API, so they never need it.

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.

swarmexec ps [service]
FlagDefaultDescription
--jsonfalseoutput 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.

swarmexec exec [flags] <target> [-- <cmd> [args...]]
FlagDefaultDescription
-i, --stdintruekeep stdin open
-t, --ttyautoallocate 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-timeout10stimeout for connecting to the agent
$ swarmexec exec web -- sh $ swarmexec exec web.2 -- cat /etc/hostname # a specific replica $ swarmexec exec -u root -w /app web -- ls -la $ swarmexec exec -e FOO=bar web -- env

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.

swarmexec cp [flags] <src> <dst>
FlagDefaultDescription
-a, --archivefalsekeep the owner and group recorded in the archive
-L, --follow-linkfalsecopy what a symlinked source points at, not the link
--max-size1Grefuse a copy larger than this (K/M/G, binary units)
-q, --quietfalseno progress output
--node—node hint/override for container-id targets
--connect-timeout10stimeout for connecting to the agent
$ swarmexec cp ./patch.sql db:/tmp/ # in $ swarmexec cp web.1:/var/log/app.log ./app.log # out $ swarmexec cp web.1:/etc/nginx.conf db.2:/tmp/ # between two containers $ swarmexec cp -L web:/var/log/current . # follow the symlink

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

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 →