Skip to main content

HOT RELOAD

Overview

When swamp serve starts with --hot-reload, it writes a PID file to .swamp/serve.pid and listens for SIGHUP. On receiving the signal, the server reloads all pulled extension bundles and refreshes the trusted collectives list without restarting.

The swamp serve reload subcommand reads the PID file and sends SIGHUP to the running process.

Flag

--hot-reload

Default: off. When enabled, the server writes .swamp/serve.pid at startup and removes it on shutdown.

Subcommand

swamp serve reload

Without --server, reads .swamp/serve.pid and sends SIGHUP to the serve process. With --server, sends a reload request to the running server over WebSocket. Both modes require the serve process to be running with --hot-reload.

Exits non-zero if the PID file does not exist (local mode) or the server is unreachable (remote mode).

Remote reload

swamp serve reload --server <url>

Sends a reload request to a remote swamp serve instance over WebSocket instead of using the local PID file and SIGHUP.

Flags

Flag Description
--server <url> WebSocket URL of the running serve instance (env: SWAMP_SERVE_URL)
--token <token> Server token for authentication. Only applies with --server. Falls back to stored credential or SWAMP_SERVER_TOKEN

Credential resolution

When --token is not provided, the client resolves credentials in this order:

  1. SWAMP_SERVER_TOKEN environment variable
  2. Stored credential for the server URL in ~/.config/swamp/servers.json (written by swamp auth server-login)

Examples

# Reload on a remote server with explicit token
swamp serve reload --server wss://swamp.acme.internal:9090 \
  --token 'paul-token.<secret>'

# Reload using stored credential
swamp serve reload --server wss://swamp.acme.internal:9090

# Reload using SWAMP_SERVE_URL (no --server needed)
export SWAMP_SERVE_URL=wss://swamp.acme.internal:9090
swamp serve reload

PID file

Location: .swamp/serve.pid (relative to the repository root).

Written at startup when --hot-reload is active. Contains the process ID of the running swamp serve instance. Removed on clean shutdown.

Reload behavior

On reload, the server:

  1. Re-reads all pulled extension bundles from .swamp/pulled-extensions/ and .swamp/bundles/
  2. Invalidates cached bundle modules
  3. Re-reads .swamp.yaml and refreshes the auto-resolver's trusted collectives list
  4. Re-reads serve.yaml and applies any trigger overrides to the running scheduler
  5. Serves subsequent requests using the updated bundles, trust list, and trigger schedules

All extension types (models, reports, workflows, vaults) are reloaded. There is no per-extension targeting — a reload refreshes everything.

Trigger overrides

Trigger overrides define or change scheduled execution for workflows without editing the workflow YAML. There are two ways to update trigger overrides on a running server:

Direct update (no reload required)

swamp workflow trigger set and swamp workflow trigger remove with --server apply overrides directly to the running scheduler over WebSocket. The override is written to serve.yaml and the scheduler is updated immediately — no --hot-reload flag or full reload is needed.

# Set a trigger override on a remote server
swamp workflow trigger set nightly-report --schedule "0 3 * * *" \
  --server wss://swamp.acme.internal:9090

# Remove a trigger override on a remote server
swamp workflow trigger remove nightly-report \
  --server wss://swamp.acme.internal:9090

Full reload

swamp serve reload re-reads all trigger overrides from serve.yaml as part of its full reload (step 4 above). Use this when overrides have been edited in serve.yaml directly rather than through the CLI.

See the Workflows reference for the full trigger set, trigger get, and trigger remove flag tables.

Platform availability

SIGHUP is a POSIX signal. Hot-reload is available on macOS and Linux. --hot-reload is not available on Windows.

← PreviousREST APINext →Webhooks