zen-proxy

# zen-proxy

> A local, zero-dependency OpenAI-compatible proxy that lets **any** coding agent (Cline, Roo Code, Continue, Aider, mimo CLI, opencode forks) use opencode's anonymous **free** Zen models — no accounts, no API keys.

## The problem this solves

opencode's Zen gateway serves its free `-free` models (`mimo-v2.5-free`, `big-pickle`, `ling-3.0-flash-fin-free`, `nemotron-*-free`, etc.) **only to requests that mimic the opencode client**.

- With the right UA plus an `x-opencode-session` header, `POST https://opencode.ai/zen/v1/chat/completions` with `Authorization: Bearer public` returns HTTP 200.
- Without the session header the gateway returns **400 MissingSessionID** — `"OpenCode's free tier can only be used in OpenCode"` (this happens even with a valid API key).
- Most agents force their own UA and never send a session header, so they cannot use the free tier directly.

zen-proxy solves this by injecting the correct `User-Agent` and a stable per-client `x-opencode-session` upstream, then re-exposing everything as a standard OpenAI-compatible API on `http://127.0.0.1:8787/v1`.

## Key facts

- **Endpoints**: `POST /v1/chat/completions` (stream + non-stream), `POST /v1/responses`, `GET /v1/models`, `GET /health`, dashboard at `GET /`.
- **Auth**: anonymous via `Bearer public`; BYOK via `defaultZenKey` config or an `x-zen-key` / real bearer token.
- **Session**: opencode's free tier requires `x-opencode-session`. The proxy mints one per client (stable per source IP, or one shared id for local clients) when the caller doesn't send one; set `injectSession: false` to disable.
- **Quota**: the free tier is per-IP; the proxy forwards the real client IP (`x-real-ip`/`x-forwarded-for` when `trustForwarded` is on), but for local/loopback clients it omits `x-real-ip` so upstream counts your machine's real IP — matching opencode direct usage and avoiding a bogus shared `127.0.0.1` bucket. Do not abuse or rotate IPs.
- **Model fallback**: tries `fallbackModels` in order on 429/5xx **and** on model-level 4xx (`Model is unavailable`, `FreeTierError`, geo-blocked or unsupported models), honors `retry-after`.
- **Endpoint routing**: Zen serves each model on either `/v1/chat/completions` or `/v1/responses`. `responsesModels` lists the patterns (`*` allowed); the proxy translates requests, tool calls, reasoning and SSE streams in both directions, so any OpenAI-compatible client works either way.
- **Free-tier gate**: opencode serves free models only to genuine agent traffic — a request must be `stream: true` **and** carry real tool definitions, otherwise it gets `403 FreeTierError: OpenCode's free tier can only be used from within OpenCode`. That is not the model being broken: such models are shown as `agent-only`, never pruned, and the proxy learns their true health from real client traffic (`ok (live traffic)`). Agents that stream and send tools (Claude Code, Cline, Roo, Continue, Aider, mimo, opencode) work as-is; one-shot calls without tools fall back transparently and the reply carries `zen_served_by` / `x-zen-served-by`. The proxy does not fake opencode's tool schemas to bypass the gate.
- **Rate limiting**: optional per-client limit on chat requests (`rateLimitMax`, `0` = off). `/health` and the dashboard are never throttled.
- **Model aliases**: `modelAliases` maps any name (e.g. `gpt-4o`) to a free model; reply model is rewritten back.
- **Config**: `zen-proxy.json` (hot-reloaded) or env vars: `PORT`, `HOST`, `ZEN_URL`, `ZEN_UA`, `INJECT_SESSION`, `AUTO_UA`, `UA_REFRESH_MS`, `PROBE_AUTH`, `RESPONSES_MODELS`, `RATE_LIMIT_MAX`, `DEFAULT_MODEL`, `FALLBACK_MODELS`, `MODEL_ALIASES`, `PROXY_KEY`, `ZEN_KEY`, `TRUST_FORWARDED`, `TIMEOUT_MS`, `CACHE_MS`, `AUTO_SYNC`, `AUTO_SYNC_MS`, `ZEN_PROXY_CONFIG`.
- **Auto model sync**: probes every upstream free model with a tiny completion (sending a session header, matching real traffic) and updates the config automatically. Only definitively-gone models (`not supported`, 404) are removed — temporary blocks (`403 FreeTierError`, geo, timeouts) keep the model configured so it recovers by itself. `probeAuth` picks the probe credentials (`auto` / `anonymous` / `key`). A GitHub Action keeps the shipped list in the repo current too.
- **Requirements**: Node.js >= 18. Zero npm dependencies.

## Install

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/12errh/zen-proxy/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/12errh/zen-proxy/main/install.ps1 | iex
```

Or clone and run: `git clone https://github.com/12errh/zen-proxy.git && cd zen-proxy && node zen-proxy.mjs`

## Point any agent at it

```jsonc
{
  "provider": {
    "zen": {
      "baseURL": "http://127.0.0.1:8787/v1",
      "apiKey": "public",
      "models": { "space-bunny-free": {} }
    }
  }
}
```

Quick test:

```bash
curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"space-bunny-free","messages":[{"role":"user","content":"say hi"}]}'
```

## More

- Full documentation: [README.md](README.md)
- Everything in one file: [llms-full.txt](llms-full.txt)
- Project: https://github.com/12errh/zen-proxy