Reference

Configuration

Configuration defines how Swarm starts, what it listens on, and how another swarm can reach it. Most local installs do not need custom settings. Direct private-LAN desktop access is not the normal safe path; use this page when you are reviewing ports, local-only defaults, or remote child deploy settings.

Config file

Swarm works out of the box for local use. If you want to expand Swarm with custom configuration, swarm.conf lets you control how it starts, which ports it listens on, and how other machines reach it. Swarm reads that startup config from $XDG_CONFIG_HOME/swarm/swarm.conf, usually ~/.config/swarm/swarm.conf on Linux.

Current network status: keep host = 127.0.0.1 for normal desktop/browser use. LAN/WireGuard remote child deploy is an advanced path with explicit preflight checks; it requires the master to listen on an address the child can reach, or a Tailscale callback URL for Tailscale transport.

After changing swarm_mode, startup_mode, host, or ports, restart Swarm so the backend starts with the new settings.

Ports

port

Backend API. Default: 7781.

desktop_port

Desktop / browser listener. Default: 5555. Set to 0 to disable the desktop listener.

peer_transport_port

Local peer transport helper used by forwarding flows such as Tailscale Serve or SSH tunneling. Default: 7791.

Local runtime

swarm

Open the terminal UI in the current directory. Starts the backend if needed.

swarm --desktop

Open Swarm Desktop in the browser. Starts the backend if needed.

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 mode

startup_mode = interactiveNormal local launcher behavior. Swarm runs when you launch it.

startup_mode = boxAlways-on box behavior. It does not by itself survive reboot, login, or logout; use systemd or another OS service manager for persistence.

swarm_mode = falseStandalone local use. This is the default.

swarm_mode = trueEnable shared swarm role, pairing, and transport settings. It does not by itself expose a loopback-only backend; restart Swarm after changing it.

child = falseThis swarm is the default master / parent role.

child = trueBootstrap this node as a child swarm that attaches back to a parent.

mode = lanUse a LAN or WireGuard callback for pairing or remote child deploy. For remote deploy, the master must bind a reachable host and advertise a reachable endpoint.

mode = tailscaleUse tailscale_url as the callback URL for pairing or remote child deploy.

swarm_nameHuman-readable name shown in onboarding and discovery surfaces.

startup_mode controls how the local process is treated. swarm_mode controls whether this node participates in shared swarm networking. mode is the pairing / callback transport, not another startup mode. Changing these startup settings requires a Swarm restart before users should expect the new behavior.

Networking

hostThe actual backend bind host. Keep it at 127.0.0.1 for normal desktop use; only change it deliberately for remote child deploy, pairing work, or another protected network path.

advertise_hostAdvanced callback metadata for pairing / 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_urlThe canonical Tailscale callback URL when using Tailscale transport.

parent_swarm_idThe stored parent relationship for child bootstrap and attach flows.

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

Direct private-LAN desktop/browser access is not the normal supported path. Do not publish Swarm on 0.0.0.0, a private LAN IP, or a WireGuard IP for casual desktop use. For remote child deploy over LAN/WireGuard, configure host, advertise_host, and advertise_port so the child can call back to the master, then restart Swarm and rerun preflight. For another device’s browser, prefer a trusted SSH tunnel or a protected private network path.

This matches the current Swarm runtime behavior: advertise_host only changes the address Swarm announces; it does not move a loopback-only listener or make 127.0.0.1 reachable from another machine. Remote deploy preflight fails until the announced endpoint and the real listener line up.

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.

Remote updateAttached remote child swarms use the remote deploy update-job path; local installed runtimes still use the normal update flow.

These overrides are documented so people, tooling, and AI assistants do not mistake them for the default path. Recommend swarm or swarm --desktop for normal local use.