Getting started

Install the gateway, write a YAML config, and send your first chat request.

Get a working edge in a few minutes: binary or Docker, one YAML file, one request.

After the basics, continue with:

Use subscriptions in any app — Claude Desktop, Codex/GPT Desktop, Cursor, Continue, Cline, Aider, Windsurf, SDKs
Claude Code + ChatGPT / SuperGrok subscriptions — OAuth login, any provider combo
Claude app + subscriptions — third-party inference in the Claude desktop app
Codex + subscriptions — Codex CLI and ChatGPT coding via ~/.codex/config.toml
Cursor + same subscriptions — point Cursor OpenAI base URL at the gateway
OAuth & upstream auth — keys, OAuth2, multi-tenant Bearer
Realtime WebSocket — production wss
Platform APIs — files, evals, agents, batches
WIF & workload identity — short-lived tokens

Requirements

Go 1.25+ (to build from source), or a release binary / Docker
A YAML config (start from gateway.example.yaml)
Provider API keys in the environment

Build and run

git clone https://github.com/inja-online/llm-gateway.git
cd llm-gateway
go build -o llm-gateway ./cmd/gateway

cp gateway.example.yaml gateway.yaml
# edit providers / keys / hooks
export OPENAI_API_KEY=sk-...
./llm-gateway -config gateway.yaml

Overrides:

GATEWAY_CONFIG=/path/to/gateway.yaml
GATEWAY_LISTEN=0.0.0.0:8787

Default listen address is localhost:8787 unless you change it.

Docker

docker compose up --build
# or
docker build -t llm-gateway:local .
docker run --rm -p 8787:8787 \
  -e OPENAI_API_KEY \
  -v "$PWD/gateway.yaml:/config/gateway.yaml:ro" \
  llm-gateway:local

Health check

curl -s http://localhost:8787/healthz
# {"status":"ok"}

GET /healthz is process liveness only (no upstream probes). It stays open even when edge_auth is enabled.

Claude Code / any app with your subscriptions

Use ChatGPT Plus/Pro, Claude Pro/Max, and/or SuperGrok through Claude Code, Cursor, Desktop apps, and more.

Claude Code · Claude app · Codex · Any app

# From a release binary:
llm-gateway helpers install          # extract shell helpers + default config
eval "$(llm-gateway helpers source)"
llm-gateway auth login chatgpt       # and/or claude, grok
export KEY=local-dev
cc-gateway-up
cc-gpt                               # or cc-grok / cc-multi / cursor-apply / apps-use-gateway
cc-gateway-logs -f                   # usage + HTTP access lines

First chat (OpenAI dialect)

curl -s http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Model routing (first match wins):

aliases in YAML
Explicit provider/model prefix
Dialect default (defaults.openai_dialect / anthropic_dialect / google_dialect)

Full routing details: README · Model routing.

How it works — request path, passthrough vs translate
OAuth & upstream auth — keys, OAuth2, client_bearer, SA
WIF & workload identity — token_file, cloud OIDC
Realtime WebSocket — OpenAI Realtime / Google Live TLS
Platform APIs — files, evals, agents, batches
Embeddings — dimensions / task_type
Claude Code — point ANTHROPIC_BASE_URL at the gateway
Claude app — third-party inference in the desktop app
Codex — Codex CLI / ChatGPT coding via config.toml
Compatibility matrix — dialect × modality × provider kind
HTTP API — full route list in the README