swarmexec

swarmexec › Docs › Configuration, flags & exit codes

Configuration, flags & exit codes_

The config file, the flags every command takes, and what the exit codes mean.

Configuration

Settings come from four layers, each overriding the one before it:

built-in defaults → config file → environment → command-line flags

A flag only overrides when you actually pass it, so a value in the file or the environment survives unless explicitly overridden.

Config file

The default path is the first of these that is set:

  1. $SWARMEXEC_CONFIG
  2. $XDG_CONFIG_HOME/swarmexec/config.yaml
  3. ~/.config/swarmexec/config.yaml

Override it with --config <path>. The file is YAML; a missing file is fine, a malformed one is an error. It is written 0600 (it may hold the shared secret). The log file lives next to it by default — ~/.config/swarmexec/swarmexec.log — unless you set --client-log-file. Keys:

KeyTypeMeaning
castringCA cert that verifies the agent's server certificate (mTLS)
certstringclient certificate — its CN is your operator identity
keystringclient private key
portintagent port (default 9443)
addr_modestringhostname (default) or ip — how to dial a node
server_namestringoverride the TLS server name used to verify the agent
agent_secretstringshared secret for a self-signed agent
agent_secret_filestringread the secret from this file (takes precedence over agent_secret)
insecureboolskip agent server-cert verification (self-signed agents)
legacy_secretboolalso send the raw shared secret, for agents older than v1.17.3 — off by default; see below
operatorstringaudit identity when no client cert is used (default: OS username)
logs.formatstringdefault log format for logs and the TUI: auto | classic | json | logfmt | gelf | raw (auto detects the format from the lines; empty = classic)
logs.min_levelstringdefault minimum level: trace..fatal (omit for no level filter)
ui.dimfloathow far the backdrop behind an open overlay is faded, a fraction 0–1 (default 0.6; 0 = no dimming)
ui.sync_docker_contextboola cluster switch in the TUI also makes that context docker's stored current one (docker context use), so your shells follow the TUI. Default false: the switch is the TUI's only, and docker in another terminal keeps going where it went. swarmexec context use always writes it — that command is an explicit choice
ui.check_updatesboollook for a newer release (default true). The TUI and swarmexec doctor ask https://swarmshell.dev/latest.json at most once a day; the request is a plain GET that sends nothing about you or your cluster, and the answer is cached in update-check.json next to the config file. A newer release shows in the TUI's status line (and in the ? title) and as a line in doctor. Builds that are not a release (dev, review-…) never ask, and offline nothing is shown. false, or SWARMEXEC_NO_UPDATE_CHECK=1, turns it off
ui.check_registryboollook up image versions in the registry (default true). For a service on repo:latest@sha256:… or a version tag the TUI asks the image's registry, with your Docker credentials, which version runs and whether a newer one exists; the answer shows after the service name ((1.2.3) ↑ 1.3.0) and in the service details. At most four lookups run at once, the results of the last 256 images are remembered, and a registry that fails keeps the earlier answer. false, or SWARMEXEC_NO_REGISTRY_CHECK=1, turns it off: no registry is contacted and no version is shown
contexts.<name>.underlaylist of CIDRsoptional, per Docker context: the hosts' own network (e.g. [10.0.0.0/16]). The Networks tab, the create-network check and the MCP networks_list then also flag overlay subnets that overlap it. Without it only the nodes' own addresses are checked. A malformed CIDR is a load error naming the key
contexts.<name>.underlay_mtuintoptional, per Docker context: the MTU of that host network (e.g. 1450 on a Hetzner private network). With it, the create-network check works out what an overlay should be told and warns when the current setting cannot fit: Docker assumes a 1500-byte underlay and subtracts 50 bytes of VXLAN overhead, so on a 1450 link its default produces frames that are silently dropped — which looks like a slow connection, not a broken one. There is deliberately no default: guessing 1500 is the very assumption this key exists to correct. Usually you do not need this key — the agents report their nodes' own link MTUs (from a read-only /sys mount) and swarmexec works the underlay out from those. Set it to override what they report, or for a cluster whose agents are older than that
contexts.<name>.{agent_secret, agent_secret_file, ca, cert, key, port, addr_mode, server_name, insecure}as the global keyoptional, per Docker context: the agent credentials and dial settings of that one cluster, so several clusters can have different secrets or CAs. Each key set here replaces the global key of the same name for this context only; keys you leave out fall back to the global value, so a config without a contexts: block behaves exactly as before. init writes these for the context it deployed to
contexts.<name>.confirm_switchbooloptional, per Docker context: switching to this context in the TUI asks for confirmation first — for production clusters, so a stray Enter in the contexts sidebar is not enough

The contexts: section holds settings for one Docker context, keyed by its name as docker context ls shows it (default for $DOCKER_HOST / the local socket). config show prints the values in effect for the context it resolves — with where each credential or dial value came from (contexts.prod.agent_secret, config file, env SWARMEXEC_PORT, flag --port, default) — plus the underlay, confirm_switch and ui.sync_docker_context:

ui: sync_docker_context: false # default: a TUI switch leaves your shell's docker context alone contexts: prod: underlay: [10.0.0.0/16] # e.g. the Hetzner private network the nodes sit on underlay_mtu: 1450 # its MTU; overlays are then checked and advised against it confirm_switch: true # the TUI asks before switching to prod agent_secret: s3cr3t # prod's own agent secret (init writes this) insecure: true addr_mode: ip

For one cluster the order is, highest first: flag → environment variable → contexts.<name>.<key> → global <key> in the file → built-in default. The environment stays above the context block because it always overrode the file: an exported SWARMEXEC_AGENT_SECRET applies to every cluster. A context's agent_secret or agent_secret_file replaces both global spellings, so it is never shadowed by a global agent_secret_file. An explicit insecure: false in a context overrides a global true. The secret's two spellings are one setting at every level: --agent-secret or SWARMEXEC_AGENT_SECRET beats an agent_secret_file from the file, and the other way round.

The logs: section sets defaults for format-aware log parsing and filtering; the logs command's --log-format / --min-level flags override them:

logs: format: auto # auto | classic | json | logfmt | gelf | raw min_level: warn # trace..fatal; omit for no level filter

A misspelled key is an error, not a silent no-op. A key that looks like a real one (confirmSwitch, agent_secrt, addr-mode) stops the command and names the key you probably meant, because a setting that quietly does nothing is worse than a refusal: confirmSwitch: true would leave the production prompt off while the file reads as if it were on. A key that is nothing like any setting is most likely a newer version's, so it is ignored with one warning: ... unknown key line on stderr and the file keeps working. An environment variable that does not parse (SWARMEXEC_PORT=80a0, SWARMEXEC_INSECURE=maybe, SWARMEXEC_UI_DIM=x) and an unknown --client-log-level are errors too (exit 2 for the flag), not a quiet fall back to the default.

Inspect the effective, merged configuration (secret masked) with:

$ swarmexec config show # or: --json

addr-mode

hostname (default) dials the node's reported hostname; ip dials its advertised address. Use ip when node hostnames aren't resolvable from your workstation — init writes addr_mode: ip into the generated config for exactly that reason. The swarm leader reports 0.0.0.0 for itself; the client recovers its real address from the raft peer list automatically.

Environment variables

VariableSets
SWARMEXEC_CONFIGconfig file path
SWARMEXEC_CA / _CERT / _KEYmTLS material
SWARMEXEC_PORTagent port
SWARMEXEC_ADDR_MODEhostname / ip
SWARMEXEC_SERVER_NAMETLS server name
SWARMEXEC_AGENT_SECRET / _FILEshared secret / secret file
SWARMEXEC_INSECUREskip verification (1/true/yes/on)
SWARMEXEC_OPERATORaudit identity
SWARMEXEC_UI_DIMoverlay backdrop dim (ui.dim)
SWARMEXEC_NO_UPDATE_CHECK1 (any value but 0/false/no/off) switches the daily release check off, whatever ui.check_updates says
SWARMEXEC_NO_REGISTRY_CHECK1 (any value but 0/false/no/off) switches the TUI's registry version lookups off, whatever ui.check_registry says
SWARMEXEC_KEYSpath to the TUI keymap file (default keys.yaml next to the config file in use, so --config moves it too)
SWARMEXEC_SSH_MULTIPLEX0/off/false/no switches ssh connection sharing off (see ssh connection sharing)
SWARMEXEC_SSH_ASKPASS0/off/false/no stops ssh from asking through swarmexec (see ssh passphrases and questions)
DOCKER_CONTEXTDocker context for the manager API
XDG_CONFIG_HOMEbase for the default config path

These configure the client, the binary you run. The agent on each node reads its own SWARMEXEC_* variables, and several names overlap — SWARMEXEC_PORT and SWARMEXEC_AGENT_SECRET mean one thing in your shell and another in the agent's container. The agent's side is listed under the agent's own flags and environment variables.

Global flags

These persistent flags apply to every command. Each command's --help lists the everyday ones; the connection flags (TLS, the agent secret, node addressing) are printed in full only by swarmexec --help and swarmexec help connection, and every other help ends with a pointer there. The CLI reference lists every command's flags, generated from that help.

FlagDefaultDescription
--config—config file path (default ~/.config/swarmexec/config.yaml)
--context—docker context for the manager API; supports ssh:// (also $DOCKER_CONTEXT)
--client-log-levelinfoswarmexec's own log verbosity: debug | info | warn | error | off (off disables logging entirely)
--client-log-file—swarmexec's own log file (default swarmexec.log next to the config file)
--info—show version, license, and contact info
--version—print the client and protocol version

Connection flags

How the client reaches the agents. They override the matching config file keys and SWARMEXEC_* variables above, so most setups set them once in the config file. swarmexec help connection prints this list.

FlagDefaultDescription
--port9443agent port
--addr-modehostnamenode dial address: hostname | ip
--ca—CA certificate to verify the agent (mTLS)
--cert—client certificate (mTLS; CN is the operator identity)
--key—client private key (mTLS)
--server-name—override TLS server name for agent verification
--agent-secret—shared secret for a self-signed agent
--agent-secret-file—file to read the shared secret from
--insecurefalseskip agent server-certificate verification
--operatorOS usernameoperator identity reported for audit
Logging. swarmexec logs in structured form (Go slog, text format) to the log file and an in-memory ring buffer. In the TUI, logs are never written to the terminal (that would corrupt the screen) — the ring buffer feeds a live in-app viewer instead (see The TUI). --client-log-level off disables logging altogether; a log-file that can't be opened is non-fatal (it falls back to the ring buffer only). These two flags are about swarmexec's own log, not the container logs swarmexec logs streams — that output is filtered with logs --min-level. They were called --log-level and --log-file before; the old names still work.

config show — inspect config

Prints the effective, merged client configuration with the secret masked.

swarmexec config show [--json]

Exit codes

CodeMeaning
0success
1a command-specific "no": stack diff found a difference (and --json still printed it), stack deploy/stack check found a problem, wait did not converge, secret rotate failed, mcp ended with an error, a cp the agent refused (policy, the size cap, no such path), or you declined a confirmation (down, volume rm, secret rotate)
2usage / flag / configuration error, a mistyped subcommand under a group (swarmexec stack chekc: unknown command "chekc" for "swarmexec stack"), or an invalid interactive selection. A wrong number of arguments also prints the command's usage line (usage: swarmexec exec [flags] <service|…> …)
125transport failure or any other runtime error — unreachable manager or agent, dial/TLS error, stream error, or a read command (volume ls, stats, doctor) that no agent answered, so an empty result cannot be mistaken for “nothing there” (mirrors Docker's 125)
129stopped by SIGHUP (the terminal went away) while a command ran
130interrupted with Ctrl-C (SIGINT): the command's context is cancelled, its cleanups run, then it exits. A second Ctrl-C ends the process immediately
143stopped by SIGTERM, handled like Ctrl-C
Nfor exec, the remote command's own non-zero exit code, propagated verbatim