Daemon Management

Warning

Daemon management is EXPERIMENTAL. The subcommands, service file format, and behavior may change in future releases.

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 or reboot.

✓ Daemon enabled — swamp serve will start automatically

All swamp serve flags are forwarded to the service definition:

Flag	Default	Description
`--port <port>`	`9090`	Port for the daemon to listen on
`--host <host>`	`127.0.0.1`	Host for the daemon to bind to
`--cert-file <path>`		Path to PEM-encoded TLS certificate
`--key-file <path>`		Path to PEM-encoded TLS private key
`--auth-mode <mode>`	`none`	Authentication mode: `none` (deprecated), `token`, or `oauth`
`--admins <principals>`		Comma-separated principal IDs for admin access
`--grant-reload <mode>`	`manual`	Policy snapshot reload: `manual` or `auto`
`--no-schedule`		Disable scheduled workflow execution
`--webhook <spec>`		Register a webhook endpoint (repeatable)
`--allowed-collectives`		Comma-separated collective slugs for OAuth admission
`--allowed-users`		Comma-separated user identifiers for OAuth admission
`--oauth-provider <url>`		OAuth authorization server URL
`--oauth-client-id <id>`		OAuth client ID (required for `oauth` mode)
`--groups-field <field>`		Userinfo field for group memberships (default: `collectives`)
`--trust-proxy`		Trust `X-Forwarded-For` for client IP in token auth
`--repo-dir <dir>`		Repository directory (env: `SWAMP_REPO_DIR`)

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.

Linux (systemd)

enable writes a systemd user service unit under ~/.config/systemd/user/. The unit uses Restart=always with RestartSec=10.

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= or @file= indirection prefixes — see Serve Flags: Secret indirection.