swarmexec

swarmexec › Docs › Install & quick start

Install & quick start_

One static binary, then one command to provision the agents.

On this page

  1. Install
  2. Quick start

Install

Requires Docker Engine 19.03 or newer (API 1.40) on the manager and on every node. swarmexec refuses an older daemon at connect with a message naming both versions, rather than connecting and then failing one view at a time. Two features want a little more from the node's daemon — live resource usage and the per-node image view need Docker 23.0 (API 1.41/1.42); below that they stay empty and say so instead of failing.

Quickest: the install script picks the build for your machine, checks it against the release's SHA256SUMS and refuses to install anything it could not verify. It never uses sudo and never edits your shell profile — read it first, it is short.

$ curl -fsSL https://swarmshell.dev/install.sh | sh $ curl -fsSL https://swarmshell.dev/install.sh | SWARMEXEC_VERSION=v1.19.2 sh # a specific release

With a package manager — then brew upgrade or scoop update brings each new release, which keeps the client in step with the agents:

$ brew install ekrotov/swarmexec/swarmexec # macOS, Linux $ scoop bucket add swarmexec https://github.com/ekrotov/scoop-swarmexec $ scoop install swarmexec # Windows

Or by hand:

The client is a single static binary. Grab the latest release build for your platform:

$ curl -fsSLo swarmexec \ https://github.com/ekrotov/swarmexec/releases/latest/download/swarmexec-linux-amd64 $ chmod +x swarmexec && sudo mv swarmexec /usr/local/bin/ $ swarmexec --version

Builds: linux-amd64, linux-arm64, darwin-arm64, darwin-amd64, windows-amd64. The agent image is public on Docker Hub as logleio/swarmexec-agent.

Updates: when a newer release is out, the TUI's status line and swarmexec doctor say so; update the way you installed (the script, brew upgrade, scoop update or a new download). The client learns of it from this site at most once a day, sending nothing about you or your cluster; ui.check_updates: false turns that off.

Shell completion

swarmexec completion bash|zsh|fish|powershell prints a completion script. It completes more than flags: exec <TAB> offers the services that exist, logs web.<TAB> their running slots, --stack <TAB> the deployed stacks and --context <TAB> your Docker contexts. Only the manager API is asked, never an agent; a completion gives up after two seconds and over ssh:// it is never allowed to prompt, so a context that would ask for a password offers nothing instead of freezing the shell.

$ swarmexec completion bash > /etc/bash_completion.d/swarmexec # or ~/.local/share/bash-completion/completions/ $ swarmexec completion zsh > "${fpath[1]}/_swarmexec" $ swarmexec completion fish > ~/.config/fish/completions/swarmexec.fish

Quick start

Point your Docker context at a Swarm manager, then provision the agents once. init creates a shared secret, deploys the agent on every node in self-signed mode, and writes a matching client config — so the other commands work immediately.

$ swarmexec --context my-swarm init # deploy agents on every node (once) $ swarmexec ps # list tasks and the node each runs on $ swarmexec exec web -- sh # shell into service "web", any node $ swarmexec logs -f web # follow a service's logs $ swarmexec port-forward db 5432 # localhost:5432 → container:5432 $ swarmexec ui # interactive TUI

Tear the agents down again with swarmexec down (it leaves your client config untouched).