Skip to main content

SET UP TLS FOR SWAMP SERVE

This guide shows you how to enable TLS on swamp serve so that workers and clients connect over wss:// and https:// instead of plain ws:// and http://.

There are two approaches:

Approach You manage certs? Extra process? Best for
Direct TLS Yes No Single-binary deployments, corporate PKI
Reverse proxy No (auto-managed) Yes Production with Let's Encrypt, easy local testing

Direct TLS

swamp serve accepts --cert-file and --key-file flags to terminate TLS itself. For the full flag and environment variable reference, see TLS and Proxies.

Generate a self-signed certificate

For local testing, generate a self-signed certificate with openssl:

openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 \
  -keyout server.key -out server.crt -days 30 -nodes \
  -subj '/CN=localhost' \
  -addext 'subjectAltName=DNS:localhost,IP:127.0.0.1' \
  -addext 'basicConstraints=critical,CA:FALSE'

Important

CA:FALSE is required. Deno's TLS stack rejects CA certificates used as end-entity certificates.

Start the server

swamp serve --cert-file server.crt --key-file server.key

The server now listens on wss:// and https:// instead of ws:// and http://.

You can also set the paths via environment variables instead of flags:

export SWAMP_SERVE_CERT_FILE=server.crt
export SWAMP_SERVE_KEY_FILE=server.key
swamp serve

Connect from a client

swamp model method run <model> <method> --server wss://localhost:9090

Trust a self-signed certificate

The compiled Swamp binary uses a baked-in certificate store. Self-signed certificates must be added to the OS trust store for the client to accept them.

On macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain server.crt

On Linux (Debian/Ubuntu):

sudo cp server.crt /usr/local/share/ca-certificates/swamp-local.crt
sudo update-ca-certificates

Note

DENO_CERT works when running Swamp via deno run but has no effect on compiled binaries. For production, use a CA-signed certificate. For details on client-side trust stores, see TLS and Proxies.

Reverse proxy with Caddy

Instead of terminating TLS in swamp serve, run a reverse proxy in front of it. Caddy auto-provisions locally-trusted certificates — no cert generation or keychain manipulation needed.

Start swamp serve on loopback

swamp serve

This listens on ws://localhost:9090 by default.

Run Caddy as a reverse proxy

caddy reverse-proxy --from localhost:9443 --to localhost:9090

Caddy generates a locally-trusted certificate for localhost on first run and listens on https://localhost:9443.

Connect from a client

swamp model method run <model> <method> --server wss://localhost:9443

For production, Caddy can auto-provision and renew Let's Encrypt certificates when given a public domain name instead of localhost.

← PreviousRemote ExecutionNext →Set Up Background Autoupdating