Zen Gateway

Running

Logout

Quick Start

Zen Gateway is a local proxy that forwards requests to OpenCode's free AI models. It accepts both OpenAI and Anthropic API formats.

1. Start the gateway

uv run python zen_client.py --serve --port 8462

2. Send a request

curl http://127.0.0.1:8462/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mimo-v2-pro-free",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Claude Code Integration

Use Zen Gateway as a free backend for Claude Code.

Step 1: Skip onboarding

In ~/.claude.json, add:

{ "hasCompletedOnboarding": true }

Step 2: Configure

Step 3: Enable 1M context (optional)

To use the extended 1M token context window, run this inside Claude Code:

/model opus[1m]

Or append it when launching from terminal:

pclaude --model 'opus[1m]'

API Reference

GET /v1/models

Returns the list of available free models.

curl http://127.0.0.1:8462/v1/models

Available Models

Model ID	Name	Status
mimo-v2-pro-free	MiMo V2 Pro Free	Free
mimo-v2-omni-free	MiMo V2 Omni Free	Free
big-pickle	Big Pickle	Free
nemotron-3-super-free	Nemotron 3 Super Free	Free
minimax-m2.5-free	MiniMax M2.5 Free	Free

POST /v1/chat/completions

OpenAI-compatible chat completions endpoint. Supports streaming.

curl http://127.0.0.1:8462/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-zen-your-key" \
  -d '{
    "model": "mimo-v2-pro-free",
    "messages": [{"role": "user", "content": "Explain quantum computing"}],
    "stream": true
  }'

POST /v1/messages

Anthropic Messages API compatible endpoint. Automatically translates to OpenAI format and back.

curl http://127.0.0.1:8462/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-zen-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "mimo-v2-pro-free",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Authentication

By default, authentication is disabled. When enabled via the Admin panel, all proxy requests require a valid API key.

API keys use the sk-zen- prefix and can be passed via:

Method	Example
Authorization header	Authorization: Bearer sk-zen-abcdef1234...
x-api-key header	x-api-key: sk-zen-abcdef1234...

Create and manage API keys from the Admin dashboard.

POST /v1/messages/count_tokens

Token estimation endpoint. Returns approximate input token count for the given messages. Used by Claude Code for context window management.

curl http://127.0.0.1:8462/v1/messages/count_tokens \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mimo-v2-pro-free",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Rate Limits & Proxy Rotation

Rate limits are IP-based, enforced by OpenCode Zen server-side. The gateway sends x-opencode-client: cli headers for higher limits.

To bypass IP-based rate limits, the gateway supports proxy rotation with three modes:

Mode	Behavior
Off	Direct connection only (default)
Auto	Direct until 429 rate-limited, then auto-switches to rotating proxies. Retries direct every 5 minutes.
On	Always route through proxies

Proxies are dynamically fetched from Geonode (HTTP/HTTPS, filtered by uptime). The pool auto-refreshes every 30 minutes. Each request retries up to 5 different proxies on failure.

Configure via the Admin panel or the proxy API endpoints below.

OpenCode Headers

The gateway automatically sets all required OpenCode headers on every upstream request:

Header	Purpose
x-opencode-client	Identifies as CLI client for higher rate limits
x-opencode-session	Stable session ID per gateway instance
x-opencode-request	Unique request ID per call
x-opencode-project	Project identifier

Stats API

All stats endpoints require admin authentication via Authorization: Bearer TOKEN.

GET /_stats

Returns gateway statistics: total requests, errors, avg latency, uptime, input/output token totals, and recent requests.

GET /_stats/requests

Paginated request log. Supports ?limit=100&offset=0. Each entry includes method, path, model, format, stream, status, latency, tokens, API key, proxy used, input messages, output content, and error.

POST /_stats/clear

Clears all request log entries from the database.

Admin API

All admin endpoints require authentication. Obtain a token via /_admin/login.

POST /_admin/login

Authenticate with admin password. Returns a session token.

curl http://127.0.0.1:8462/_admin/login \
  -H "Content-Type: application/json" \
  -d '{"password": "admin"}'

GET /_admin/api-keys

List all API keys with prefix, name, created date, last used, and active status.

POST /_admin/api-keys

Create a new sk-zen-* API key. Returns the full key (shown once).

POST /_admin/api-keys/delete

Revoke an API key by ID.

GET /_admin/settings

Get all gateway settings (require_auth, proxy_enabled, etc).

POST /_admin/settings

Update a setting. Body: {"key": "require_auth", "value": "true"}

POST /_admin/change-password

Change admin password. Body: {"old_password": "...", "new_password": "..."}

GET /_admin/proxy

Returns proxy pool status: mode, enabled, using_proxy, rate_limited_direct, total/alive/dead counts.

POST /_admin/proxy/toggle

Cycle proxy mode: Off → Auto → On → Off.

POST /_admin/proxy/refresh

Trigger immediate proxy pool refresh from Geonode.

POST /_admin/proxy/settings

Update proxy filters. Body: {"min_uptime": 80}