zen-proxy

ZEN·PROXY

a local OpenAI-compatible proxy that unlocks opencode's anonymous free tier — for any agent.

Zen Proxy is a zero-dependency, locally-run OpenAI-compatible proxy that unlocks opencode's Zen free tier for any coding agent — not just opencode.

opencode gives you free models like deepseek-v4-flash-free, mimo-v2.5-free, and nemotron — but only to requests that look like they come from opencode itself: the right User-Agent and an x-opencode-session header. Most agents force their own identity and get shut out with 400 MissingSessionID ("OpenCode's free tier can only be used in OpenCode") or 429 FreeUsageLimitError. Zen Proxy quietly speaks for them: it injects the correct User-Agent, mints stable per-client session IDs, forwards your real IP, and re-exposes everything as a standard /v1/chat/completions + /v1/models API.

The result: whatever tool you love — Cline, Roo Code, Continue, Aider, mimo, or a plain curl — can now ride opencode's free models with zero accounts, zero API keys, and zero config beyond a baseURL.

What it enables:

• Free OpenAI-compatible models outside opencode — bring your own agent, keep the free tier
• Anonymous access with no accounts or keys (Bearer public), or bring your own Zen key (BYOK) for your own quota
• Smart model fallback — when one free model is saturated, it rolls to the next
• Model aliases — call them gpt-4o or claude-3-5, get routed to free models
• Per-IP fairness — real client IPs are forwarded (local clients fall back to your machine's real IP, same quota bucket as opencode direct)
• A retro-zine management dashboard — stats, one-click model tests, live config, and logs at http://127.0.0.1:8787/
• One-file install on Linux, macOS, and Windows with a single curl

why it exists

opencode's free -free models (deepseek-v4-flash-free, nemotron, mimo-v2.5-free, …) are only served to requests that mimic the real client. Since opencode started requiring an x-opencode-session header, anything without it gets 400 MissingSessionID: "OpenCode's free tier can only be used in OpenCode" — even with a valid API key. Most coding agents — like the mimo CLI fork — force their own identity and get slammed with that error (or 429 FreeUsageLimitError).

zen-proxy injects the correct User-Agent and a stable synthetic x-opencode-session per client, then re-exposes everything as a plain OpenAI API. No accounts, no API keys, no source patches.

works with: mimo cli, Cline, Roo Code, Continue, Aider, opencode forks — anything that lets you set a baseURL + apiKey.

dashboard

The management UI runs on http://localhost:8787 (or http://127.0.0.1:8787) once the proxy is running — live stats, one-click model tests, auto-sync status, config editing, and server logs.

install

Requires Node.js ≥ 18.

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

irm https://raw.githubusercontent.com/12errh/zen-proxy/main/install.ps1 | iex

Or just clone and run — it's a single file, no npm install:

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

usage

node zen-proxy.mjs            # or the installer's `zen-proxy` launcher
# dashboard → http://127.0.0.1:8787/

point your agent at it

Cline / Roo / Continue / Aider / mimo — anywhere you configure an OpenAI-compatible provider:

{
  "provider": {
    "zen": {
      "baseURL": "http://127.0.0.1:8787/v1",
      "apiKey": "public",
      "models": { "deepseek-v4-flash-free": {} }
    }
  }
}

Quick test:

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

the dashboard

• Overview — upstream health, uptime, request counters, live recent-request feed with status + latency
• Models — add/remove allowed models, pick the default, one-click Test per model
• Settings — edit host, port, upstream URL, User-Agent, proxy key, BYOK key, timeout, fallback list, aliases; saved to zen-proxy.json and applied instantly
• Logs — live terminal-style log tail

Set proxyKey and the dashboard, /api/*, chat completions, and /v1/models all require it (/health stays open for uptime monitors).

configuration

Config lives in zen-proxy.json (auto-created on first run, hot-reloaded when edited — the dashboard writes it too). Env vars can override at startup.

Env vars: HOST, PORT, ZEN_URL, ZEN_UA, INJECT_SESSION (0 to disable), DEFAULT_MODEL, FALLBACK_MODELS (JSON), MODEL_ALIASES (JSON), PROXY_KEY, ZEN_KEY, TRUST_FORWARDED=1, TIMEOUT_MS, CACHE_MS, AUTO_SYNC (0 to disable), AUTO_SYNC_MS, ZEN_PROXY_CONFIG (custom config path).

bring your own key

Anonymous public access rides opencode's shared free pool (per-IP quota, sometimes saturated). For stable, reliable use set defaultZenKey to your own free Zen key — or send it per request as x-zen-key / a non-public bearer token.

api surface

systemd (linux)

Install as a service via install.sh (it prompts you), or manually:

sudo systemctl enable --now zen-proxy

caveats

• This rides opencode's anonymous free tier: per-IP request/daily quotas and a shared pool that's sometimes saturated. Don't rotate/abuse IPs or run heavy workloads anonymously.
• The -free models are "as-is" free tiers — expect rate limits and occasional provider errors.
• For anything serious, BYOK.

zen-proxy · anonymous free tier · no accounts · no keys · 100% local

go make some noise.

MIT License