DAEMON MANAGEMENT

swamp serve daemon manages swamp serve as a platform-native system daemon. On macOS it registers a launchd LaunchAgent; on Linux it creates a systemd user service.

Subcommands

enable

swamp serve daemon enable

Generates and registers a platform-native service definition with all serve flags baked in. The daemon starts immediately and will restart automatically on failure. Whether it starts on reboot depends on the service type — see Platform Details below.

✓ Daemon enabled — swamp serve will start automatically

Daemon-specific flags

Forwarded serve flags

All swamp serve flags are forwarded to the service definition:

swamp serve daemon enable does not carry SWAMP_OAUTH_CLIENT_ID into the service definition. Pass --oauth-client-id instead.

Example with a custom port and TLS:

swamp serve daemon enable --port 8080 --cert-file cert.pem --key-file key.pem --auth-mode token

disable

swamp serve daemon disable

Unloads the running daemon and removes the service definition.

✓ Daemon disabled — service definition removed

status

swamp serve daemon status

Reports the daemon's enabled/running state, PID, and log path:

Status:  running
Enabled: yes
PID:     65055
Logs:    ~/Library/Logs/swamp

When no daemon is configured:

Status: not configured
Run swamp serve daemon enable to set up the daemon

Platform Details

macOS (launchd)

enable writes a LaunchAgent plist under ~/Library/LaunchAgents/. The plist uses KeepAlive to restart the process on exit and ThrottleInterval set to 10 seconds to prevent rapid restart loops. LaunchAgents are per-user services — they run only while the user is logged in and start again on the next login, not on reboot itself.

Linux (systemd)

Without --user, enable writes a system-wide unit under /etc/systemd/system/. System services start on boot and run independently of any user session.

With --user, enable writes a user service unit under ~/.config/systemd/user/. User services run only while the user has an active login session. To make a user service start on boot without logging in, enable lingering: loginctl enable-linger $USER.

Both use Restart=always with RestartSec=10.

Swamp data and config directories

Swamp loads every extension — including extensions already pulled into the repository — through an embedded runtime under the Swamp data directory: SWAMP_HOME when set, otherwise ~/.swamp resolved from HOME (or USERPROFILE).

Every Swamp process needs a swamp-club.com credential to start — see Swamp Account Requirement. The daemon reads the credential that swamp auth login stores in auth.json, and the cached proof in auth_verified.json, from the Swamp config directory, resolved in this order:

enable sets both SWAMP_HOME and SWAMP_CONFIG_DIR in the generated service definition — Environment= lines in the systemd unit, EnvironmentVariables entries in the launchd plist. Each is the absolute path of that directory as resolved in the environment of the user who ran enable, so the daemon reads the same credentials that user is signed in with. Sign in as that user before running enable.

A daemon that does not own the config directory, such as a system service running as root, reads the credential and proof but never writes to the directory. A running serve renews its proof once it is over 7 days old and holds the renewed proof in memory. The proof on disk is kept fresh by the signed-in user's own Swamp runs; if that user runs nothing for 14 days, it expires and the daemon must reach swamp-club.com when it next starts.

swamp worker daemon enable sets SWAMP_CONFIG_DIR the same way. A worker daemon enabled by a version without the account requirement lacks it. When it finds no credential at all, it passes through its serve as a remote worker; re-run swamp worker daemon enable as the signed-in user to give it the user's credential. Serve daemons already set SWAMP_CONFIG_DIR and need no change.

A running daemon is checked when it starts, not on every request.

A service definition written by hand must set SWAMP_HOME or HOME. When none of SWAMP_HOME, HOME, or USERPROFILE is set, extension loading is disabled and Swamp logs a warning beginning Extension loading is unavailable: no swamp data directory found (none of SWAMP_HOME, HOME, or USERPROFILE is set). Scheduled workflows that use pulled or user extension types then fail with Unknown model type.

Environment=SWAMP_HOME=/opt/swamp
Environment=SWAMP_CONFIG_DIR=/home/alice/.config/swamp

Versions from 20260921.211448.0 up to, but not including, 20260930.184839.0 set only SWAMP_HOME, so a token or oauth daemon they installed cannot start. Re-run swamp serve daemon enable to rewrite the service definition.

File Permissions

Service definition files are written with 0600 permissions. This is because the service definition may contain webhook secrets or other sensitive flags passed to swamp serve. To avoid embedding literal secrets in the service definition, use the @env=, @file=, or @vault= indirection prefixes — see Serve Flags: Secret indirection.