Skip to main content
The reference deployment runs one Gateway process, one SQLite database file, and a TLS reverse proxy. Use it when you are self-hosting without the managed control plane. For multi-tenant hosted deployments, pair the Gateway with the Control Plane package for orgs, projects, teams, billing account records, usage events, secret references, and audit export.

​
Docker Compose

From the repo root: 
docker compose -f deploy/reference/docker-compose.yml up
The Gateway listens on 7331 inside the compose network and Caddy exposes HTTP/TLS. The compose file mounts a SQLite volume at /data and reads short-lived bearer grants from /data/tokens.json. If /data/tokens.json does not exist, the Gateway starts with an empty in-memory token set and denies token auth until you mount or write a token store. Issue a local token grant: 
bunx smithers-orchestrator token issue --scopes run:read,run:write,approval:submit --ttl 1h
Copy the resulting grant into the token store used by the deployment. Revoke it with: 
bunx smithers-orchestrator token revoke <token>

​
Single Host

Use deploy/reference/systemd/smithers-gateway.service for the Gateway process and deploy/reference/systemd/smithers-caddy.service for Caddy. Copy smithers-gateway.env.example to /etc/smithers/gateway.env, then set: 
SMITHERS_DB_PATH=/var/lib/smithers/smithers.db
SMITHERS_TOKEN_STORE=/etc/smithers/tokens.json
SMITHERS_GATEWAY_MODULE=/etc/smithers/gateway.mjs
SMITHERS_GATEWAY_HEADERS_TIMEOUT_MS=30000
SMITHERS_GATEWAY_REQUEST_TIMEOUT_MS=60000
SMITHERS_GATEWAY_MODULE can export register(gateway) or a default function. Register workflows there.

​
Gateway Environment

VariableDefaultPurpose
PORT7331Gateway listen port inside the container or host.
SMITHERS_DB_PATH/data/smithers.dbSQLite database path made available to the gateway module for workflow storage.
SMITHERS_TOKEN_STORE/data/tokens.jsonJSON token grant store used by token auth.
SMITHERS_GATEWAY_MODULE/workspace/gateway.mjsModule that registers workflows on startup.
SMITHERS_GATEWAY_HEARTBEAT_MS15000WebSocket heartbeat interval.
SMITHERS_GATEWAY_EVENT_WINDOW10000Per-run replay window size (number of events) for streamRunEvents.
SMITHERS_GATEWAY_HEADERS_TIMEOUT_MS30000Maximum time to receive complete HTTP headers.
SMITHERS_GATEWAY_REQUEST_TIMEOUT_MS60000Maximum time to receive and parse a complete HTTP request, including body.

​
Kubernetes

The minimal manifests in deploy/reference/k8s/ create:
  • a smithers namespace
  • a single Gateway Deployment
  • a ConfigMap (smithers-gateway-config) supplying Gateway environment variables
  • a SQLite PersistentVolumeClaim
  • a token Secret
  • a Service and Ingress
Edit deploy/reference/k8s/secret.example.yaml to set the bearer token and update the host in deploy/reference/k8s/ingress.yaml before applying: 
kubectl apply -f deploy/reference/k8s/

​
Event Stream Reconnection

Pass afterSeq with the last seen sequence number when reconnecting to a stream. The Gateway then:
  • Replays any missed events still within the bounded per-run window.
  • Emits a GapResync frame (fields: fromSeq, toSeq, run snapshot) if the window has truncated, then resumes with available events.
  • Sends Heartbeat frames on a separate interval; these do not carry run events.
All HTTP responses include X-Smithers-API-Version: v1.