RUN AS A SYSTEM DAEMON

This guide shows you how to run swamp serve as a system daemon that restarts automatically on failure.

Prerequisites

Every Swamp process needs a swamp-club.com account to start, the daemon included — see Swamp Account Requirement. Sign in as the user who will run swamp serve daemon enable, before you enable it:

swamp auth login

The daemon reads that user's credential from their Swamp config directory, in every --auth-mode. For --auth-mode token or --auth-mode oauth, the credential needs the serve:* scope; a collective token in SWAMP_API_KEY works too. For OAuth mode without browser interaction, SWAMP_API_KEY also needs the oauth:manage scope — see Deploy with Headless OAuth. To reuse an OAuth client, pass --oauth-client-id and --oauth-client-secret-file to swamp serve daemon enable: it does not carry SWAMP_OAUTH_CLIENT_ID into the service definition.

Enable the daemon

From your repository directory, run:

swamp serve daemon enable

✓ Daemon enabled — swamp serve will start automatically

The daemon starts immediately and restarts automatically if it exits. If it keeps restarting, check its logs for an account error: the daemon cannot find a credential, or has not been able to verify it. Sign in as the enabling user and re-run swamp serve daemon enable.

On Linux this installs a system-wide service that starts on boot. To install as a per-user service instead, add --user:

swamp serve daemon enable --user

Per-user services (systemd --user) run only while the user has an active login session. To start the service on boot without logging in, enable lingering:

loginctl enable-linger $USER

On macOS the daemon is always a per-user LaunchAgent regardless of --user. It runs while the user is logged in and starts again on the next login.

Pass serve flags

All swamp serve flags carry through to the daemon. For example, to run on a custom port with TLS and token auth:

swamp serve daemon enable --port 8080 \
  --cert-file cert.pem --key-file key.pem \
  --auth-mode token --admins 'user:paul'

The flags are baked into the service definition. To change them, disable the daemon and re-enable with the new flags.

Check daemon status

swamp serve daemon status

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

The Logs path points to where the daemon writes its output. Check there for errors if the daemon is enabled but not running.

Disable the daemon

swamp serve daemon disable

✓ Daemon disabled — service definition removed

This stops the running daemon and removes the service definition so it will not start on reboot.

Platform notes

• macOS: The daemon runs as a launchd LaunchAgent (per-user). It uses KeepAlive for automatic restarts with a 10-second throttle interval. It runs while the user is logged in.
• Linux (system): Without --user, the daemon runs as a system-wide systemd service that starts on boot. It uses Restart=always with RestartSec=10.
• Linux (user): With --user, the daemon runs as a systemd user service. It uses Restart=always with RestartSec=10 but only runs while the user has an active session (unless lingering is enabled).

Service definition files are written with 0600 permissions because they may contain webhook secrets or other sensitive values.

For the full flag reference, see Daemon Management.