Quickstart

1. Add the gateway to your agent image

The gateway ships as a static binary plus a Python integration in the spekoai/gateway image. Add both to your existing agent Dockerfile:

FROM spekoai/gateway:latest AS speko

FROM python:3.12-slim
# ... your existing agent build ...

COPY --from=speko /usr/local/bin/speko-gateway /usr/local/bin/speko-gateway
COPY --from=speko /opt/speko/python /opt/speko/python
RUN pip install /opt/speko/python

# Run the gateway alongside your agent process

Start speko-gateway before (or supervised alongside) your agent process — it is one binary with no arguments; all configuration is environment variables.

2. Configure BYOK mode

The minimum viable environment is a local auth token plus one provider key:

export SPEKO_LOCAL_AUTH_TOKEN=$(openssl rand -hex 32)
export SPEKO_DEEPGRAM_BYOK_API_KEY=dg_your_key

Every secret also accepts an exclusive _FILE variant (SPEKO_DEEPGRAM_BYOK_API_KEY_FILE=/run/secrets/deepgram) for file-mounted secrets.

3. Use it from a LiveKit agent

from livekit.agents import AgentSession
from speko_gateway.livekit import STT

session = AgentSession(
    stt=STT(),   # connects to the gateway's Unix socket automatically
    # ... llm, tts, vad as usual ...
)

STT() defaults to language="en", provider="auto", model="auto", credential_source="auto", and a 16 kHz stream. The plugin reads SPEKO_SOCKET_PATH and SPEKO_LOCAL_AUTH_TOKEN from the environment. Automatic credential selection uses managed credentials when SPEKO_API_KEY or SPEKO_API_KEY_FILE is configured, and BYOK otherwise.

4. Or call the local API directly

curl -s --unix-socket /run/speko/runtime.sock http://speko-gateway/v1/sessions \
  -H "Authorization: Bearer $SPEKO_LOCAL_AUTH_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "stt",
    "execution": { "provider_route": "provider_direct", "credential_source": "byok", "relay_policy": "forbidden" },
    "request": { "provider": "deepgram", "language": "en" },
    "media": { "encoding": "pcm_s16le", "sample_rate_hz": 16000, "channels": 1 }
  }'

The response includes a stream_url; attach the WebSocket there and start sending audio.

5. Go managed (optional)

Set a Speko API key, then select managed credentials for the requests that Speko should route and bill:

export SPEKO_API_KEY=sk_speko_...

BYOK and managed requests can coexist in one gateway process. See Modes for selection rules, and the hardened docker-compose example for production container settings (read-only rootfs, dropped capabilities, non-root user).