Reference
Configuration
Every environment variable, grouped by surface — the compose stack, the gateway, the CLI and clients, and the developer-deployed agent-loop and executor.
Every knob is an environment variable. Defaults are chosen so an unedited .env boots a working local stack; the tables below are for anyone who wants non-default ports, credentials, or behavior. Longer stories link to the guide that owns them.
The compose stack
These live in .env (copy .env.example). Every one has a working default baked into docker-compose.yml, so a missing .env still boots.
| Variable | Default | Meaning |
|---|---|---|
POSTGRES_USER | teaspill | Postgres role (catalog store; also feeds Electric). |
POSTGRES_PASSWORD | teaspill | Postgres password. Change it before exposing the port. |
POSTGRES_DB | teaspill | Database name. |
POSTGRES_PORT | 5432 | Host-side published port. |
RESTATE_INGRESS_PORT | 8080 | Restate ingress (invocations in). |
RESTATE_ADMIN_PORT | 9070 | Restate admin API (deployment registration). |
RESTATE_METRICS_PORT | 9071 | Prometheus metrics. |
RESTATE_NODE_PORT | 5122 | Node-to-node (reserved; unused single-node). |
ELECTRIC_PORT_HOST | 3000 | Host-side published port for the shape API. |
ELECTRIC_INSECURE | true | Dev-only. Disables shape-API auth. Set false before exposing Electric. |
DURABLE_STREAMS_PORT | 4437 | Host-side published port for the history store. |
DURABLE_STREAMS_LOG | info | History-store log filter (error…trace). |
GATEWAY_PORT | 8787 | Host-side published port for the gateway. |
Published ports are for local debugging. In production the gateway is the only surface you expose; the other services stay on the internal network. See Self-hosting.
Gateway
The gateway reads everything from env. The defaults below are the standalone defaults; the compose stack overrides the upstream URLs to internal service names.
| Variable | Default | Meaning |
|---|---|---|
PORT | 8787 | Listen port. |
HOST | 0.0.0.0 | Listen host. |
TEASPILL_TENANT | default | Deployment tenant used to expand /a/<type>/<id>. |
RESTATE_INGRESS_URL | http://localhost:8080 | Restate ingress (compose: http://restate:8080). |
RESTATE_ADMIN_URL | http://localhost:9070 | Restate admin API (compose: http://restate:9070). |
ELECTRIC_URL | http://localhost:3000 | Electric shape API (compose: http://electric:3000). |
DURABLE_STREAMS_URL | http://localhost:4437 | History store (compose: http://durable-streams:4437). |
DATABASE_URL | — | Postgres for API keys. Optional only if a bootstrap key is set. |
GATEWAY_BOOTSTRAP_API_KEY | — | Dev-only literal key accepted without a database row. |
GATEWAY_MAX_BODY_BYTES | 1048576 | Body cap (1 MiB) on commands and proxied writes. Oversize → 413. |
GATEWAY_UPSTREAM_HEADERS_TIMEOUT_MS | 120000 | Upstream first-byte timeout; must exceed the long-poll park. |
GATEWAY_JWT_SECRET | — | HS256 secret enabling the browser read-token path. Unset ⇒ API keys only. |
GATEWAY_JWT_CLOCK_TOLERANCE_SECONDS | 60 | Clock-skew leeway when verifying a read token's expiry. |
GATEWAY_CORS_ALLOW_ORIGINS | * | Allowed origins for GET on /streams/* and /shapes/*. |
LOG_LEVEL | info | Structured-logging level. |
OTEL_EXPORTER_OTLP_ENDPOINT | — | When set, spans export via OTLP/HTTP; otherwise tracing is a no-op. |
Auth-related variables are covered in depth in Auth & API keys.
CLI and clients
The CLI and the SDK clients are gateway clients. Their env names are deliberately distinct from the gateway's own server-side variables.
| Variable | Default | Meaning |
|---|---|---|
TEASPILL_GATEWAY_URL | http://localhost:8787 | Gateway base URL. |
TEASPILL_API_KEY | — | Gateway API key. |
TEASPILL_TENANT | default | Deployment tenant. |
TEASPILL_DEPLOYMENT_URL | http://host.docker.internal:9080 | Deployment URL(s) teaspill dev registers (comma-separated). |
Agent-loop and executor
The two developer-deployed services (the reference deployment's agent-loop and executor-host) read these. The defaults shown are the overlay values.
| Variable | Default | Meaning |
|---|---|---|
PORT | 9080 / 9081 | Listen port (agent-loop / executor). |
TEASPILL_GATEWAY_URL | http://gateway:8787 | Gateway for health-wait and registration. |
TEASPILL_INGRESS_URL | http://restate:8080 | Restate ingress for tool and workspace clients. |
TEASPILL_STREAMS_URL | http://durable-streams:4437 | History store for event and exec output. |
TEASPILL_DEPLOYMENT_URL | http://agent-loop:9080 / http://executor:9081 | The URL Restate dials — service name in-network; http://host.docker.internal:<port> for host-run. Never localhost. |
TEASPILL_API_KEY | — | Gateway API key for registration. |
DATABASE_URL | synthesized by compose | Catalog connection. Absent ⇒ a loud degraded mode. |
TEASPILL_MIGRATE | 1 | Run idempotent catalog migrations on boot. |
TEASPILL_MIGRATIONS_DIR | /app/drizzle | Migration directory (in the image). |
TEASPILL_RECONCILER | on | The background consistency loop. off disables it. |
TEASPILL_IDLE_ARCHIVE_MS | — (30 min) | Idle auto-archive delay override, ms. Unset ⇒ the 30-minute default; 0 disables auto-archive. Short values are for testing the archive/resurrect round-trip only — never run production with a short window. |
TEASPILL_WORKSPACE_ADAPTER | docker | Adapter that private workspaces run in. |
TEASPILL_EXECUTOR_ADAPTER | docker | Executor adapter. local-unrestricted opts into host exec (doubly gated). |
Demo-agent gating
The reference deployment's demo agents are served only when their key or opt-in is present; a missing one skips the agent cleanly rather than crashing.
| Variable | Meaning |
|---|---|
ANTHROPIC_API_KEY | Enables the model-backed demo agents (both the native and Claude Agent SDK demos need it). |
TEASPILL_DEMO_CASDK | Set to 1 to additionally serve the Claude Agent SDK demo agent. |
TEASPILL_DEMO_MODEL | Overrides the demo model. |
TEASPILL_CASDK_SESSION_DIR | Session directory for the Claude Agent SDK demo. |