Configuration
Every environment variable the gateway reads.
The gateway is configured entirely through environment variables. Every secret-bearing variable also accepts an exclusive _FILE variant (NAME_FILE=/path) — setting both NAME and NAME_FILE is an error, secret files are capped at 64 KiB, and an empty file is an error.
Core
| Variable | Default | Purpose |
|---|---|---|
SPEKO_LOCAL_AUTH_TOKEN | required | Bearer token for the local API |
SPEKO_API_KEY | unset | Enables Speko-managed mode |
SPEKO_SOCKET_PATH | /run/speko/runtime.sock | Absolute Unix socket path |
SPEKO_MAX_SESSIONS | 100 | Per-process session capacity |
SPEKO_LOCAL_MAX_SESSION_DURATION | 24h | Provider-direct session hard deadline |
SPEKO_TELEMETRY_DISABLED | false | Opt out of optional telemetry |
SPEKO_RUNTIME_INSTANCE_ID | hostname | Non-secret process identity |
SPEKO_WORKLOAD_TYPE | agent when an ID is set | Dashboard workload category |
SPEKO_WORKLOAD_ID | unset | Stable workload identity for the dashboard |
Control plane (managed mode)
| Variable | Default | Purpose |
|---|---|---|
SPEKO_CONTROL_PLANE_URL | https://gateway.speko.dev | Speko control plane |
SPEKO_JWKS_URL | <control-plane>/.well-known/jwks.json | Plan signing keys |
SPEKO_PLAN_ISSUER | control-plane URL | Required plan issuer |
SPEKO_PLAN_AUDIENCE | speko-runtime | Required plan audience |
SPEKO_INSTANCE_HEARTBEAT_INTERVAL | 20s | Worker heartbeat interval |
Warm plan pool (managed mode)
| Variable | Default | Purpose |
|---|---|---|
SPEKO_WARM_PLAN_TARGET | 4 | Prefetched plans per route; 0 disables |
SPEKO_WARM_ROUTES | unset | Pre-declared routes: kind:provider[:model[:language]], comma-separated |
SPEKO_WARM_TTS_MAX_CHARACTERS | 100000 | Character allowance requested for warmed TTS routes |
BYOK provider keys
Set any of these to enable that provider for BYOK requests:
SPEKO_ALIBABA_BYOK_API_KEY, SPEKO_ASSEMBLYAI_BYOK_API_KEY, SPEKO_CARTESIA_BYOK_API_KEY, SPEKO_DEEPGRAM_BYOK_API_KEY, SPEKO_ELEVENLABS_BYOK_API_KEY, SPEKO_FISH_BYOK_API_KEY, SPEKO_GLADIA_BYOK_API_KEY, SPEKO_GOOGLE_BYOK_ACCESS_TOKEN, SPEKO_GRADIUM_BYOK_API_KEY, SPEKO_HUME_BYOK_API_KEY, SPEKO_INWORLD_BYOK_API_KEY, SPEKO_MINIMAX_BYOK_API_KEY, SPEKO_MODULATE_BYOK_API_KEY, SPEKO_OPENAI_BYOK_API_KEY, SPEKO_RIME_BYOK_API_KEY, SPEKO_SMALLEST_BYOK_API_KEY, SPEKO_SONIOX_BYOK_API_KEY, SPEKO_XAI_BYOK_API_KEY
Provider-specific configuration:
- Google STT additionally requires
SPEKO_GOOGLE_STT_ENDPOINTset to a project-scoped recognizer URL; the catalog row stays visible but unroutable until it is configured. - TTS voice overrides use
SPEKO_<PROVIDER>_BYOK_TTS_VOICEwhen a deployment needs a provider-specific default.
Container hardening
The published image is distroless and runs as UID/GID 65532. The reference docker-compose file runs it with read_only: true, cap_drop: ALL, no-new-privileges, a named volume on /run/speko, and a small noexec tmpfs on /tmp. Because the documented setup shares one container between agent and gateway, the agent process can read the container environment — use separate containers when you need process-level credential isolation.