RUN AS A SYSTEM DAEMON

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

Prerequisites

If the daemon uses --auth-mode token or --auth-mode oauth, authenticate with swamp auth login or set SWAMP_API_KEY with serve:* scope before enabling. For OAuth mode without browser interaction, SWAMP_API_KEY also needs the oauth:manage scope — see Deploy with Headless OAuth.

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.

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.