Run your LLM gateway.

01 Run locally

The local workflow uses Docker for Postgres and Redis, then starts the proxy, admin API, and Vite dashboard with the repo's dev target.

# start local services, then the dev runtime
docker compose up -d postgres redis
make ui-install
make dev

The dev script prints a login key and starts the data plane on :8080, the admin API on :8081, the dashboard on :3333, and metrics on :9090/metrics.

02 Open the dashboard

Open http://localhost:3333/ and paste the adm_dev_... login key printed by make dev. The dashboard talks to the admin API through /api.

# local listeners
data plane   http://localhost:8080
admin API    http://localhost:8081
dashboard    http://localhost:3333
metrics      http://localhost:9090/metrics

03 Connect providers

Add at least one provider account before creating user onboarding. Provider credentials are stored by the gateway and injected only into upstream requests.

# Dashboard → Providers → New Provider
deepseek     upstream=https://api.deepseek.com
openai       upstream=https://api.openai.com
anthropic   upstream=https://api.anthropic.com
passthrough configured from the provider catalog

Use model aliases only when you need an override. Built-in routing already handles catalog-backed public model names, while manual aliases can redirect a selected model globally or per team.

# Dashboard → Aliases
corp-deepseek-v4-pro  → provider account deepseek-primary
custom-fast           → provider account openai-compat-fast

04 Issue team keys

Create a team, add a user, and create that user's key. The returned cpk_live_... secret is shown once.

# Dashboard → Teams → New Team → Users → New Key
name:    "Platform team"
user:    "agent@acme.example"
key:     cpk_live_••••••••   copy now

If PROXY_PUBLIC_BASE_URL is configured, key creation also returns Pi onboarding snippets for the extension and model discovery flow.

05 Connect Pi

The first-class gateway plugin is in development. Today, the same core integration runs through the personalized corp-proxy extension generated during key onboarding. Save it at Pi's agent extension path, then restart Pi.

# copy the generated Extension tab into
~/.pi/agent/extensions/corp-proxy.ts

# optional overrides for the repo copy
export CORP_PROXY_BASE_URL=https://proxy.example.com
export CORP_PROXY_KEY=cpk_live_••••

On startup, the extension discovers approved models, attaches the current session and canonical repository identity to proxy traffic, capability-detects project memory tools, checks for updates, and registers /quota when the Pi build supports commands.

# available from the current integration
models              dynamic provider catalog
retrieve_memories   scoped project knowledge lookup
record_memory       durable project observation
/quota              spend balance + cache trend
telemetry           session · project · version · health

Canonical JSONL session upload is a separate client opt-in. Enable it only when the key has the required session-log scope and the team has chosen that evidence boundary.

06 Configure insight services

The insight plugin contract is in development. The target architecture runs processors independently over gRPC while the gateway owns canonical session parsing, configuration matching, tags, run provenance, and project-knowledge materialization.

# Admin → Insights → Services
name          Primary insights
gRPC target   insights.internal:50051
transport     TLS # or plaintext on a trusted private network
timeout       120000 ms
health        Test → service + version

Create one or more configurations after registering a healthy service. Every matching active configuration runs independently for an eligible session.

# Admin → Insights → Configurations
scope         global | tenant | project
instructions  what this processor should look for
tags          current only | allow proposed additions
summaries     session and/or per-insight
input bounds  max transcript items + characters
revision      increments when configuration changes

The Tags tab governs the shared vocabulary and usage counts. Runs records the configuration revision, project, input hash, status, summary, insight count, usage, warnings, failures, and timing. Canonical Pi session upload remains a separate client opt-in and is required before a session can enter this processor path.

07 Send traffic

Use the team key as the API key. OpenAI-compatible traffic goes to /openai/v1 or /deepseek/v1; Anthropic Messages traffic goes to /anthropic/v1/messages.

$ curl http://localhost:8080/deepseek/v1/chat/completions \
  -H "Authorization: Bearer cpk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "corp-deepseek-v4-pro",
    "messages": [{"role":"user","content":"hi"}]
  }'

✓ routed · quota checked · credential injected · usage recorded

The call appears in Usage. If conversation capture is enabled, the prompt and response body also appear in Payloads and session views.

The same key can inspect its own live quota. The response reports API-key, user, and team balances, identifies the tightest remaining daily and monthly allowance, and includes a seven-day cache trend. Finite balances include both exact spend values and used/remaining percentages.

$ curl http://localhost:8080/proxy/v1/quota \
  -H "Authorization: Bearer cpk_live_••••"

# effective balance plus every applicable enforcement scope
daily.remaining_cents
daily.used_percent
daily.remaining_percent
monthly.remaining_cents
monthly.used_percent
monthly.remaining_percent
scopes[].daily | scopes[].monthly

# current 7-day cache usage vs the preceding period
cache_trend.current.cache_read_share_percent
cache_trend.current.request_cache_hit_percent
cache_trend.cache_read_share_change_points
cache_trend.daily[]

Pi users with the corp-proxy extension can run /quota to see user and team limits as used/remaining percentages, API-key limits in dollars, and the cache trend without leaving their session.

08 Deploy to production

Production uses pinned registry images. Only the public data-plane port belongs behind internet-facing TLS; the admin API, metrics, and dashboard should bind a private or Tailscale address.

# build, push, deploy, then verify
make deploy
make verify-deploy

# required production secrets include
PROXY_POSTGRES_DSN=postgres://...
PROXY_REDIS_ADDRESS=...
PROXY_CREDENTIAL_ENCRYPTION_KEY=base64-32-byte-key
PROXY_AUTH_HASH_PEPPER_REF=secret/proxy/key-hash-pepper
PROXY_SECRET_SECRET_PROXY_KEY_HASH_PEPPER=same value for proxy and admin
PROXY_PUBLIC_BASE_URL=https://proxy.example.com