RUN AS A SYSTEM DAEMON

This guide shows you how to run swamp serve as a system daemon that starts automatically on boot and restarts 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.

Enable the daemon

From your repository directory, run:

swamp serve daemon enable

✓ Daemon enabled — swamp serve will start automatically

The daemon starts immediately. It will also start on reboot and restart automatically if it exits.

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

swamp serve daemon enable --user

On macOS the daemon is always a per-user LaunchAgent regardless of --user.

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. It uses KeepAlive for automatic restarts with a 10-second throttle interval.
• Linux: The daemon runs as a systemd user service. It uses Restart=always with RestartSec=10.

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.