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 SIGHUP, 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. Serves subsequent requests using the updated bundles and trust list

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

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