# 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](/llm-gateway/guides/app-integrations/) — Claude Desktop, Codex/GPT Desktop, Cursor, Continue, Cline, Aider, Windsurf, SDKs  
- [Claude Code + ChatGPT / SuperGrok subscriptions](/llm-gateway/guides/claude-code-subscriptions/) — OAuth login, any provider combo  
- [Claude app + subscriptions](/llm-gateway/guides/claude-desktop-subscriptions/) — third-party inference in the Claude desktop app  
- [Codex + subscriptions](/llm-gateway/guides/codex-subscriptions/) — Codex CLI and ChatGPT coding via `~/.codex/config.toml`  
- [Cursor + same subscriptions](/llm-gateway/guides/cursor-subscriptions/) — point Cursor OpenAI base URL at the gateway  
- [OAuth & upstream auth](/llm-gateway/guides/oauth-auth/) — keys, OAuth2, multi-tenant Bearer  
- [Realtime WebSocket](/llm-gateway/guides/realtime-websocket/) — production `wss`  
- [Platform APIs](/llm-gateway/guides/platform-apis/) — files, evals, agents, batches  
- [WIF & workload identity](/llm-gateway/guides/wif-identity/) — short-lived tokens  

## Requirements

- Go **1.25+** (to build from source), or a [release binary](https://github.com/inja-online/llm-gateway/releases) / Docker
- A YAML config (start from [`gateway.example.yaml`](https://github.com/inja-online/llm-gateway/blob/master/gateway.example.yaml))
- Provider API keys in the environment

## Build and run

```bash
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:

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

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

## Docker

```bash
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

```bash
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](/llm-gateway/guides/claude-code-subscriptions/)** · **[Claude app](/llm-gateway/guides/claude-desktop-subscriptions/)** · **[Codex](/llm-gateway/guides/codex-subscriptions/)** · **[Any app](/llm-gateway/guides/app-integrations/)**

```bash
# 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)

```bash
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):

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

Full routing details: [README · Model routing](https://github.com/inja-online/llm-gateway/blob/master/README.md#model-routing).

## Next

- [How it works](/llm-gateway/how-it-works/) — request path, passthrough vs translate  
- [OAuth & upstream auth](/llm-gateway/guides/oauth-auth/) — keys, OAuth2, `client_bearer`, SA  
- [WIF & workload identity](/llm-gateway/guides/wif-identity/) — `token_file`, cloud OIDC  
- [Realtime WebSocket](/llm-gateway/guides/realtime-websocket/) — OpenAI Realtime / Google Live TLS  
- [Platform APIs](/llm-gateway/guides/platform-apis/) — files, evals, agents, batches  
- [Embeddings](/llm-gateway/guides/embeddings/) — dimensions / task_type  
- [Claude Code](/llm-gateway/guides/claude-code/) — point `ANTHROPIC_BASE_URL` at the gateway  
- [Claude app](/llm-gateway/guides/claude-desktop-subscriptions/) — third-party inference in the desktop app  
- [Codex](/llm-gateway/guides/codex-subscriptions/) — Codex CLI / ChatGPT coding via `config.toml`  
- [Compatibility matrix](/llm-gateway/reference/compatibility-matrix/) — dialect × modality × provider kind  
- [HTTP API](https://github.com/inja-online/llm-gateway/blob/master/README.md#http-api) — full route list in the README