USE EXTRA HEADERS WITH PROXIES

Some reverse proxies and tunnels require clients to present custom HTTP headers on every request — for example, a Tunnel-Token header for Cloudflare Tunnel or a X-Auth-Request header for an OAuth2 proxy. This guide shows how to configure Swamp clients to inject those headers automatically.

For TLS setup (direct certificates or reverse proxy with Caddy), see Set Up TLS for swamp serve.

Set a single extra header

Export SWAMP_SERVE_EXTRA_HEADERS with a Name: value string before running any client command:

export SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: abc123"

All subsequent --server commands and swamp worker connect calls in this shell session include the header.

Set multiple extra headers

Separate headers with newlines. Use ANSI-C quoting ($'...') in bash/zsh to embed literal newlines:

export SWAMP_SERVE_EXTRA_HEADERS=$'Tunnel-Token: abc123\nX-Custom-Org: ops-team'

Run a remote workflow through a proxy

export SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: abc123"
swamp workflow run deploy --server wss://swamp.example.com:9090 \
    --token ci-runner.9ce100bf...

The extra headers are sent alongside the authentication token on the WebSocket upgrade request.

Connect a worker through a tunnel

SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: abc123" \
    swamp worker connect wss://swamp.example.com:9090 \
    --token ci-runner.9ce100bf...

Keep secrets out of shell history

Avoid pasting raw tokens into your shell. Source the header value from a file or a secret manager:

export SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: $(cat /run/secrets/tunnel-token)"

Or in a systemd unit:

[Service]
Environment=SWAMP_SERVE_EXTRA_HEADERS=Tunnel-Token: %d/tunnel-token
LoadCredential=tunnel-token:/etc/swamp/tunnel-token

Related

• TLS and Proxies — full reference for SWAMP_SERVE_EXTRA_HEADERS format, reserved headers, and validation rules
• Set Up TLS for swamp serve — certificate setup and reverse proxy configuration with Caddy
• Serve Flags — all swamp serve flags and environment variables