Reference

Configuration

Configuration defines the local daemon listener, storage roots, ports, swarm identity, and topology metadata. Most installs should not hand-edit it: start Swarm, complete onboarding, and let Desktop manage additional runtimes. Use this page when you are reviewing local-only defaults, network reachability, or advanced overrides.

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 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 for normal local desktop/browser use. Do not publish the backend on 0.0.0.0, a LAN address, or a WireGuard address unless you are deliberately setting up a protected managed-host or child-runtime path and have checked reachability.

After changing listener addresses or ports, restart Swarm so the daemon starts with the new settings.

Storage

Swarm was created so you do not have to manage markdown files as product state. Sessions, agents, flows, permissions, workspace registrations, settings, 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, main Pebble database, secret store, generated artifacts, reports, worktrees, and remote-deploy session data.

/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 helper used by forwarding flows such as Tailscale Serve or SSH tunneling. Default: 7791.

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

Open the terminal UI in the current directory and connect to the local daemon.

swarm --desktop

Open Swarm Desktop in the browser and connect to the local daemon.

swarm server on

Start the backend without opening a UI.

swarm server status

Show health, lane, listen URL, and PID.

swarm server off

Stop the backend.

Swarm identity

swarm_nameHuman-readable name shown in onboarding, discovery, and manage-swarm 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 or Add Swarm flows.

Topology state

childBootstrap marker for a child swarm. Desktop and attach flows should manage this for normal use.

swarm_roleOptional role marker. For example, managed hosts use a managed role after pairing.

parent_swarm_idStored parent relationship for child bootstrap and attach flows.

pairing_stateLocal pairing state, such as unpaired, pending approval, paired, or rejected.

managed_host_sync_*Managed-host sync metadata written by managed-host link flows.

deploy_container_*

remote_deploy_*Bootstrap metadata for container and remote-deploy child attach paths.

Treat these as runtime-owned topology fields. Prefer Add Swarm, pairing, managed-host, or deploy flows instead of hand-editing relationship state.

Networking

hostThe backend bind host. Keep it at 127.0.0.1 for normal desktop use.

advertise_hostAdvanced callback metadata for pairing and child work. It does not make a loopback-only Swarm reachable from another machine.

advertise_portAdvanced callback metadata paired with advertise_host. Default backend port: 7781.

tailscale_urlCanonical persisted Tailscale URL for explicit pairing and peer endpoint configuration.

Direct private-LAN desktop/browser access is not the normal supported path. For managed-host or child-runtime work, the announced endpoint and the real listener must line up before another runtime can call back successfully.

Advanced

bypass_permissionsBypass normal tool permission prompts. Plan mode still stays plan mode, and leaving plan mode still requires approval.

retain_tool_output_historyKeep sanitized tool and permission output in persisted history. The default keeps the more private placeholder behavior.

dev_modeSource-checkout development only. Allows local child image rebuilds from dev_root.

dev_rootSource checkout root recorded when development-only child image rebuilds are enabled.

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.