RUN A WORKER IN DOCKER
This guide shows you how to run a single Swamp worker inside a Docker container, connected to an orchestrator on your host machine.
For deploying a scalable pool of workers, see Run a Fleet with Docker Compose.
Build the worker image
Create a Dockerfile that installs Swamp from the install script:
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates tini \
&& rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://swamp-club.com/install.sh | sh
ENTRYPOINT ["/usr/bin/tini", "-s", "--", "swamp"]The entrypoint runs Swamp under tini so that processes a step leaves behind
are reaped instead of lingering as zombies until the container exits.
Build the image:
docker build -t swamp-worker .Generate a self-signed TLS certificate
The orchestrator requires TLS for off-loopback connections. For local testing, generate a self-signed certificate:
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 \
-pkeyopt ec_param_enc:named_curve \
-keyout key.pem -out cert.pem -days 30 -nodes \
-subj "/CN=localhost" \
-addext "subjectAltName=DNS:localhost,DNS:host.docker.internal" \
-addext "basicConstraints=CA:FALSE"basicConstraints=CA:FALSE is required — without it, the Deno runtime rejects
the certificate as a CA certificate used as a server certificate.
ec_param_enc:named_curve is required with the LibreSSL openssl that ships
with macOS. Without it, LibreSSL writes the key with explicit curve parameters
and swamp serve exits at startup with
Error: keys may not be consistent: KeyMismatch. OpenSSL 3 accepts the flag and
produces the same pair either way.
Include host.docker.internal in the SAN so the worker can verify the
certificate when connecting from inside the container.
Start the orchestrator
Authenticate with swamp auth login or set SWAMP_API_KEY with serve:* scope
— see Swamp Account Requirement.
The orchestrator vouches for the workers it enrolls, so run Swamp
v20261008.183339.0-sha.231eda34 or later and start it while swamp-club.com is
reachable. Then start swamp serve with TLS, token authentication, at least one
admin principal, and the host bound to 0.0.0.0 so the container can reach it:
swamp serve \
--host 0.0.0.0 \
--cert-file cert.pem \
--key-file key.pem \
--auth-mode token \
--admins 'user:<you>' \
--trusted-hosts host.docker.internal--admins is required with --auth-mode token; see
Set Up Token Authentication.
--trusted-hosts allows the Host: host.docker.internal header that Docker
sends. Without it, the orchestrator rejects the connection. See
Serve Flags for the full flag
reference.
Create tokens
In a separate terminal, in the same repository, mint a server token for the worker and create a worker enrollment token:
swamp access token mint worker-token --principal user:worker --duration 24h
swamp worker token create docker-worker --duration 24hThe server token's plaintext is stored in a vault. Print it with:
swamp access token reveal worker-token --yesThe value has the form worker-token.<secret>. Save the enrollment token value
too — it is shown once.
Run the worker container
The worker needs no swamp-club.com key: it passes the account check through the orchestrator that enrolls it.
docker run -d --name swamp-worker \
-e SWAMP_ORCHESTRATOR_URL=wss://host.docker.internal:9090 \
-e SWAMP_SERVER_TOKEN=worker-token.<secret> \
-e SWAMP_WORKER_TOKEN=docker-worker.<secret> \
-e SWAMP_WORKER_LABELS=env=docker \
-e SWAMP_CA_CERT=/certs/cert.pem \
-v "$(pwd)/cert.pem:/certs/cert.pem:ro" \
swamp-worker worker connectOn Linux with Docker Engine rather than Docker Desktop, host.docker.internal
does not resolve inside a container by default. Add
--add-host host.docker.internal:host-gateway to the docker run command.
The enrollment token expires after 24 hours. To keep the worker past then,
follow
Rotate a Worker Enrollment Token.
A worker given its token in SWAMP_WORKER_TOKEN holds a rotated token in memory
only, so recreate the container with the new token before it next restarts.
SWAMP_CA_CERT makes the worker trust the self-signed CA certificate, which is
bind-mounted into the container. Images with a Swamp release older than
v20260922.185723.0-sha.33229b53 also need -e DENO_CERT=/certs/cert.pem; see
TLS and Proxies.
For an orchestrator older than v20261008.183339.0-sha.231eda34, or an image
based on Alpine, give the worker its own key: add
-e SWAMP_API_KEY=swamp_org_<hex> and -e SWAMP_SIGNIN_TOKEN=<signin-token>
from a collective token. See
Remote workers.
Refer to Worker Commands for the full list of environment variables and flags.
Verify enrollment
Confirm the worker appears in the pool:
swamp worker listThe worker should show as connected with the env=docker label.
Run a placed workflow
Create a workflow that targets the Docker worker by label and run it:
jobs:
- name: test
steps:
- name: hello
task:
type: behavior
behavior: my-behavior
methodName: run
labels:
env: dockerswamp workflow run my-workflowThe step dispatches to the Docker worker. Confirm completion with
swamp workflow status my-workflow.
Related
- Run a Fleet with Docker Compose — scale to multiple workers
- Worker Commands — full CLI and environment variable reference
- Enrollment Tokens — token lifecycle and machine binding
- Set Up TLS for swamp serve — TLS with a reverse proxy