swarmexec › Docs › Configuration, flags & exit codes
Configuration, flags & exit codes_
The config file, the flags every command takes, and what the exit codes mean.
On this page
Configuration
Settings come from four layers, each overriding the one before it:
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:
$SWARMEXEC_CONFIG$XDG_CONFIG_HOME/swarmexec/config.yaml~/.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:
| Key | Type | Meaning |
|---|---|---|
ca | string | CA cert that verifies the agent's server certificate (mTLS) |
cert | string | client certificate — its CN is your operator identity |
key | string | client private key |
port | int | agent port (default 9443) |
addr_mode | string | hostname (default) or ip — how to dial a node |
server_name | string | override the TLS server name used to verify the agent |
agent_secret | string | shared secret for a self-signed agent |
agent_secret_file | string | read the secret from this file (takes precedence over agent_secret) |
insecure | bool | skip agent server-cert verification (self-signed agents) |
legacy_secret | bool | also send the raw shared secret, for agents older than v1.17.3 — off by default; see below |
operator | string | audit identity when no client cert is used (default: OS username) |
logs.format | string | default log format for logs and the TUI: auto | classic | json | logfmt | gelf | raw (auto detects the format from the lines; empty = classic) |
logs.min_level | string | default minimum level: trace..fatal (omit for no level filter) |
ui.dim | float | how far the backdrop behind an open overlay is faded, a fraction 0–1 (default 0.6; 0 = no dimming) |
ui.sync_docker_context | bool | a 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_updates | bool | look 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_registry | bool | look 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>.underlay | list of CIDRs | optional, 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_mtu | int | optional, 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 key | optional, 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_switch | bool | optional, 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:
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:
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:
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
| Variable | Sets |
|---|---|
SWARMEXEC_CONFIG | config file path |
SWARMEXEC_CA / _CERT / _KEY | mTLS material |
SWARMEXEC_PORT | agent port |
SWARMEXEC_ADDR_MODE | hostname / ip |
SWARMEXEC_SERVER_NAME | TLS server name |
SWARMEXEC_AGENT_SECRET / _FILE | shared secret / secret file |
SWARMEXEC_INSECURE | skip verification (1/true/yes/on) |
SWARMEXEC_OPERATOR | audit identity |
SWARMEXEC_UI_DIM | overlay backdrop dim (ui.dim) |
SWARMEXEC_NO_UPDATE_CHECK | 1 (any value but 0/false/no/off) switches the daily release check off, whatever ui.check_updates says |
SWARMEXEC_NO_REGISTRY_CHECK | 1 (any value but 0/false/no/off) switches the TUI's registry version lookups off, whatever ui.check_registry says |
SWARMEXEC_KEYS | path to the TUI keymap file (default keys.yaml next to the config file in use, so --config moves it too) |
SWARMEXEC_SSH_MULTIPLEX | 0/off/false/no switches ssh connection sharing off (see ssh connection sharing) |
SWARMEXEC_SSH_ASKPASS | 0/off/false/no stops ssh from asking through swarmexec (see ssh passphrases and questions) |
DOCKER_CONTEXT | Docker context for the manager API |
XDG_CONFIG_HOME | base 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.
| Flag | Default | Description |
|---|---|---|
--config | — | config file path (default ~/.config/swarmexec/config.yaml) |
--context | — | docker context for the manager API; supports ssh:// (also $DOCKER_CONTEXT) |
--client-log-level | info | swarmexec'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.
| Flag | Default | Description |
|---|---|---|
--port | 9443 | agent port |
--addr-mode | hostname | node 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 |
--insecure | false | skip agent server-certificate verification |
--operator | OS username | operator identity reported for audit |
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.
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | a 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) |
2 | usage / 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|…> …) |
125 | transport 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) |
129 | stopped by SIGHUP (the terminal went away) while a command ran |
130 | interrupted with Ctrl-C (SIGINT): the command's context is cancelled, its cleanups run, then it exits. A second Ctrl-C ends the process immediately |
143 | stopped by SIGTERM, handled like Ctrl-C |
N | for exec, the remote command's own non-zero exit code, propagated verbatim |