swarmexec

docker exec, logs and port-forward for any container in a Docker Swarm — from one terminal, without SSH to the node that runs it.

🌐 Website and full documentation: swarm-exec.cloud-surfers.net — docs in English, Deutsch, Español, Français and Polski · release notes

Docker Swarm schedules tasks from the manager, but a container's shell, its logs, a port nobody published and the volume on its disk live on one node — and the manager API reaches none of them. swarmexec (also written swarm-exec) puts a small agent on every node and asks it directly.

What it does

• Exec anywhere — swarmexec exec web -- sh opens a shell in the task, on whatever node it runs. Targets →
• Logs of a service or a whole stack — every replica in one stream, following containers across replacement. logs →
• Port-forward to ports nobody published, without touching the stack. port-forward →
• A terminal UI for services, volumes, networks, secrets, configs and nodes — across several clusters in one session, with live CPU/RAM and health. The TUI →
• Stack diff and a pre-deploy check for CI — a content diff of a file against the deployed stack, and a security gate before stack deploy. stack diff →
• Disk cleanup per node — what stopped containers, images, build cache, networks and volumes cost on each node, a per-category prune that never touches swarm overlays, and a cluster-wide prune schedule the agents run themselves. Pruning a node →
• Secret rotation that keeps the name — swarmexec secret rotate NAME --from-file new.txt gives a secret in use new content without a _v2 rename; resumable if interrupted. secret rotate →
• A security report of the whole cluster, as Markdown you can file and compare. security report →
• An MCP server for AI assistants — swarmexec mcp lets Claude Code and friends read status, logs and stack diffs of the services you opt in by label; read-only, labels hidden from the assistant. mcp →
• Its own identity and audit — mTLS or a connection-bound shared secret, an audit log, an optional policy file. Authentication →

Apache-2.0, self-hosted, no telemetry, no node limit. Docker Engine 19.03 or newer.

Install

curl -fsSL https://swarm-exec.cloud-surfers.net/install.sh | sh   # Linux, macOS — verifies the checksum
brew install ekrotov/swarmexec/swarmexec                         # macOS, Linux
scoop bucket add swarmexec https://github.com/ekrotov/scoop-swarmexec
scoop install swarmexec                                          # Windows

Or take a binary from the latest release. Install →

Quick start

swarmexec --context prod init      # deploy the agent to every node, write the client config
swarmexec ps                       # what you can exec into, and on which node
swarmexec exec web -- sh           # a shell in a task of the service "web"
swarmexec ui                       # the terminal UI

Quick start →

How it works

your terminal ──gRPC (mTLS or bound secret)──> agent on node N ──docker.sock──> container
      │
      └── Docker manager API: which node runs the task, and its container id

The agent runs as a global Swarm service, one task per node, with the node's Docker socket mounted. The client asks the manager where the target runs and connects straight to that node's agent — there is no mesh between agents. How it works →

Documentation

The full documentation lives at swarm-exec.cloud-surfers.net/docs: configuration · Docker contexts and SSH · all commands · the TUI · monitoring · policy file · exit codes

In this repository:

• docs/manual-setup.md — deploying the agent by hand with your own CA, the agent and client flags, troubleshooting, production notes.
• docs/related-work.md — how swarmexec compares with d4s, swarmcli, Portainer, Swarmpit, Komodo and the older swarm-exec scripts.
• DEVELOPMENT.md — building, tests, the documentation site, the release pipeline.
• CONTRACT.md and proto/swarmexec.proto — the wire protocol; agent/README.md, client/README.md — the two components' internals.

The agent image is public on Docker Hub as logleio/swarmexec-agent. Source: gitlab.logle.io/cs-public/swarm-remote-exec, mirrored to github.com/ekrotov/swarmexec.

License

swarmexec is open source under the Apache License 2.0.

Copyright 2026 Cloud Surfers GmbH.

Contributions are welcome under the same license and require a DCO sign-off (git commit -s) — see CONTRIBUTING.md.

If you redistribute swarmexec — as source, as a binary, or inside a derivative work — the license requires you to keep the LICENSE and NOTICE files with it, so the attribution to this project travels along. Modified files must be marked as changed.