swarmagent.dev
GitHub
DocsModelsPricingNewsContactGitHub

Documentation feedback

Help us improve this page.

About

We use submissions to improve Swarm and may reply if you include an email. Human verification is required. See our Privacy Policy.

Reference

Configuration

Configuration defines the local daemon listener, storage roots, ports, Swarm identity, and advanced runtime settings. Most installs should not hand-edit it: start Swarm and complete onboarding first. Use this page when you are reviewing local-only defaults, network reachability, or advanced overrides.

These settings are documented for reference only. Unless you plan to run Swarm Agent in development mode, you likely do not need to change any configuration.

Config file

Swarm stores daemon startup configuration in swarm.conf. On Linux, the daemon startup config path is /etc/swarmd/swarm.conf.

The filename is always swarm.conf. When systemd provides an explicit CONFIGURATION_DIRECTORY through ConfigurationDirectory=swarmd, Swarm uses that directory as the config root and reads the file at CONFIGURATION_DIRECTORY/swarm.conf.

The config file uses one key = value entry per line. Blank lines and lines beginning with # are ignored. Duplicate or unknown active keys are rejected. Swarm creates a missing config on the first daemon start, writes it with mode 0600, and appends supported migration keys to older configs when they are missing.

The config file defines daemon startup settings. The runtime model is a daemon plus clients such as the terminal UI and Desktop.

Keep host = 127.0.0.1. Current releases reject non-loopback hosts, including 0.0.0.0, LAN addresses, and WireGuard addresses. For access from another trusted device, keep the daemon loopback-only and use an SSH tunnel or Tailscale forwarding.

Restart Swarm after changing startup configuration. Listener, transport, permission, history, and diagnostic settings are read when the daemon starts.

Storage

Swarm was created so you do not have to manage markdown files as product state. Sessions, permissions, workspace registrations, Workspace Actions, settings, model assignments, and runtime metadata are daemon-owned state, stored through the storage contract and managed through Swarm's UI, API, and CLI surfaces.

On Linux, Swarm stores the main daemon database at /var/lib/swarmd/swarmd.pebble. Provider credentials and other saved secrets use a separate local secret Pebble store at /var/lib/swarmd/swarmd-secrets.pebble; saved credential records are encrypted at rest before they are written there.

swarm.conf is only the daemon startup config. It sets listener, identity, and topology bootstrap values. It is not the database and it is not where normal Swarm objects are edited.

/var/lib/swarmd
Daemon data, the main Pebble database, the encrypted credential store, and daemon-owned workspace data and reports.
/etc/swarmd
Daemon startup configuration, including swarm.conf.
/var/cache/swarmd
Daemon caches.
/run/swarmd
Volatile runtime files, sockets, locks, PID files, and port records.
/var/log/swarmd
Logs and diagnostic artifacts.

systemd directory environment overrides are authoritative when explicitly present: STATE_DIRECTORY, CACHE_DIRECTORY, RUNTIME_DIRECTORY, CONFIGURATION_DIRECTORY, and LOGS_DIRECTORY.

Ports

port
Backend API listener. Default: 7781.
desktop_port
Desktop / browser listener. Default: 5555. Set to 0 to disable the desktop listener.
peer_transport_port
Local-only peer transport listener used by forwarding flows such as Tailscale Serve or SSH tunneling. New configs start at 7791; when migrating an older config, Swarm selects an available port at or above that value and records it.

Daemon lifecycle

The runtime model is a daemon plus clients. The launcher, service manager, terminal UI, and Desktop control whether the daemon is running; the config file stores startup settings for the daemon.

swarm
Ensure the installed daemon is ready, then open the terminal UI in the current directory.
swarm --desktop
Ensure the installed daemon is ready, then open Swarm Desktop in the browser.
swarm start
Start the installed daemon service and wait for it to become ready.
swarm restart
Restart the installed daemon service and wait for it to become ready.
swarm status
Show the installed service state, daemon health, local URL, and PID when available.
swarm stop
Stop the installed daemon service.
swarm open
Ensure the installed daemon is ready, then open its Desktop URL.

Swarm identity

swarm_nameHuman-readable name shown in onboarding and discovery surfaces. It may be blank in a fresh config and set later during onboarding.
desktop_onboarding_completeDesktop onboarding completion marker. Normal setup writes this for you.

Do not hard-code a name just to make a config file look complete. A new Swarm can bootstrap with an empty swarm_name, then set the name through onboarding.

Topology state

childFirst-run bootstrap marker for a child Swarm. The default is false; normal setup flows manage it when needed.

swarm_role is legacy ignored input, not an active setting. Runtime placement, relationships, and workspace bindings live in daemon-owned topology records rather than swarm.conf; do not hand-edit that state.

Networking

hostThe backend bind host. The default is 127.0.0.1, and current releases accept loopback hosts only.
advertise_hostCanonical LAN host or IP that another machine should use for this Swarm. It may be blank and does not change the loopback-only backend listener. Supply a host or IP only, without a scheme, path, or port.
advertise_portCanonical LAN port paired with advertise_host. It defaults to port; the initial default is 7781.
tailscale_urlPersisted Tailscale URL used for bootstrap and connectivity. Leave it blank when no manual Tailscale address is configured.

Do not expose the daemon directly to a LAN or public network. Keep it on loopback and use an SSH tunnel or Tailscale forwarding for trusted remote access.

Advanced

bypass_permissionsBypass normal tool permission prompts. The default is false. Plan mode remains plan mode, and leaving plan mode still requires approval.
retain_tool_output_historyKeep sanitized tool and permission output in persisted history. The default is false, which keeps the privacy-preserving placeholder behavior.
v3_diagnosticsPersist verbose V3 diagnostic events. The default is false; enable it temporarily because diagnostics may contain request context.
provider_api_diagnosticsLog sanitized outbound provider request and response payloads. The default is false. This setting is separate from v3_diagnostics and redacts API keys and authorization headers.
long_session_diagnosticsRecord bounded metadata-only diagnostics for investigating long-session memory use and lag. The default is false; artifacts are stored under the canonical logs root.
dev_modeEnable source-checkout development update behavior. The default is false; leave it disabled for normal installations.
dev_rootAbsolute source-checkout root used by the development update flow. Leave it blank unless a source-checkout rebuild has recorded it.
SWARMD_URLProcess environment override for the UI/API client target. Normal swarm launches choose the backend automatically.
SWARMD_TOKENProcess environment token for protected backend APIs. It is not required for normal local launches.