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. Whether it starts on reboot depends on the service type — see Platform Details below.

✓ Daemon enabled — swamp serve will start automatically

Daemon-specific flags

Flag	Description
`--user`	Install as a per-user service (systemd `--user` / launchd agent). Without this flag on Linux, the unit is installed system-wide under `/etc/systemd/system/`. On macOS the service is always a LaunchAgent (per-user); `--user` is accepted but has no additional effect.

Forwarded serve flags

All swamp serve flags are forwarded to the service definition:

Flag	Default	Description
`--config <path>`		Path to a YAML config file (default: `.swamp/serve.yaml`). See Serve Flags — Config file
`--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`
`--remote-only`	(off)	Disable local (loopback) execution — all steps must declare placement (env: `SWAMP_REMOTE_ONLY`)
`--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)
`--oauth-client-name <name>`		Override the OAuth `client_name` used during dynamic client registration. Default: `swamp-serve-{repoName}-{hostname}` (env: `SWAMP_OAUTH_CLIENT_NAME`)
`--groups-field <field>`		Userinfo field for group memberships (default: `collectives`)
`--trust-proxy`		Trust `X-Forwarded-For` for client IP in token auth
`--verify-on-enroll`		Run a fleet probe on each enrolling worker before it becomes schedulable
`--restricted-model-types <types>`		Comma-separated model types that require `admin` on `access:*` to create or run
`--restricted-commands <cmds>`		Comma-separated server commands that require admin authority (e.g. `datastore.namespace.list,extension.install`)
`--trusted-hosts <hosts>`		Comma-separated hostnames to trust for Host header validation (env: `SWAMP_TRUSTED_HOSTS`)
`--group-refresh-interval <duration>`	`4h`	How often to re-fetch IdP group memberships for active server tokens. Accepts seconds (`14400`), explicit units (`4h`, `30m`), or `0` to disable. Requires `--auth-mode oauth` (env: `SWAMP_GROUP_REFRESH_INTERVAL`)
`--approve-requires-explicit-grant`		Require a grant that names `approve` to decide a manual approval gate. Requires `--auth-mode token` or `oauth` (env: `SWAMP_APPROVE_REQUIRES_EXPLICIT_GRANT`)
`--auto-resume`	(off)	Resume a suspended run once an approval made through serve decides its last gate (env: `SWAMP_AUTO_RESUME`)
`--dashboard`	(off)	Enable the web dashboard at `/dashboard` (env: `SWAMP_DASHBOARD`)
`--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. 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 directory

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).

enable sets SWAMP_HOME in the generated service definition — an Environment= line in the systemd unit, an EnvironmentVariables entry in the launchd plist — to the data directory of the user who ran enable.

A service definition written by hand must set SWAMP_HOME or HOME, for example Environment=SWAMP_HOME=/opt/swamp. 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.

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.