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...Run a worker daemon through a tunnel
swamp worker daemon enable writes SWAMP_SERVE_EXTRA_HEADERS from your shell
into the service. Keep the variable across sudo, which drops it by default:
export SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: abc123"
sudo --preserve-env=SWAMP_SERVE_EXTRA_HEADERS \
swamp worker daemon enable wss://swamp.example.com:9090 \
--token ci-runner.9ce100bf...Check that enable lists the header name in its output:
Extra headers from SWAMP_SERVE_EXTRA_HEADERS: Tunnel-TokenIf the line is missing, the service was written without the headers. See Extra headers.
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)"In a systemd unit you write yourself, keep the header in a file only root can
read and load it with EnvironmentFile=. Write the file:
sudo install -m 600 -o root -g root /dev/null /etc/swamp/tunnel-headers.env
sudoedit /etc/swamp/tunnel-headers.envwith one line:
SWAMP_SERVE_EXTRA_HEADERS="Tunnel-Token: abc123"Then reference it from the unit's [Service] section:
[Service]
EnvironmentFile=/etc/swamp/tunnel-headers.envThis applies to a unit you maintain by hand. The unit
swamp worker daemon enable generates already holds the headers, readable only
by its owner, and enable rewrites it each time it runs, so edits to it are
lost. To change a generated worker's headers, re-run enable with
SWAMP_SERVE_EXTRA_HEADERS set, as in
Run a worker daemon through a tunnel.
Related
- TLS and Proxies — full reference for
SWAMP_SERVE_EXTRA_HEADERSformat, reserved headers, and validation rules - Set Up TLS for swamp serve — certificate setup and reverse proxy configuration with Caddy
- Serve Flags — all
swamp serveflags and environment variables