# OpenCode Zen Proxy

OpenAI-compatible proxy for [OpenCode](https://opencode.ai)'s free Zen models. Use DeepSeek V4 Flash, MiniMax M2.5, Kimi K2.5, and more — for free — in any OpenAI-compatible tool (Cursor, Claude Code, Continue, etc.).

## How it works

```
Your tool → opencode-proxy (localhost:6446) → opencode.ai/zen/v1
```

The proxy injects the required `x-opencode-*` headers that OpenCode Zen's free API expects. Your tools talk standard OpenAI protocol to the proxy; the proxy handles the rest.

## Quick Start

```bash
# Build
go build -o opencode-proxy .

# Run (no auth)
./opencode-proxy

# Run with API key protection
./opencode-proxy -api-key "your-secret-key"

# Or via env var
export OPENCODE_PROXY_KEY="your-secret-key"
./opencode-proxy
```

The server starts on `http://127.0.0.1:6446`.

## CLI Flags

| Flag | Default | Description |
|------|---------|-------------|
| `-port` | `6446` | Server port |
| `-host` | `127.0.0.1` | Server host |
| `-api-key` | (none) | API key to protect the proxy |
| `-version` | — | Show version and exit |

Also reads `OPENCODE_PROXY_KEY` environment variable if `-api-key` is not set.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/health` | Health check |
| `GET` | `/v1/models` | List available free models |
| `POST` | `/v1/chat/completions` | Chat completions (streaming + non-streaming) |

### Authentication

If `-api-key` is set, all requests require one of:
- `Authorization: Bearer <key>`
- `x-api-key: <key>`

## Available Models

| Model ID | Alias | Notes |
|----------|-------|-------|
| `deepseek-v4-flash-free` | `deepseek`, `deepseek-v4` | Solid, recommended |
| `big-pickle` | `pickle` | Stealth model (= DeepSeek V4 Flash) |
| `minimax-m2.5-free` | `minimax`, `m2.5` | Strong coding model |
| `kimi-k2.5-free` | `kimi`, `k2.5` | Best free model |
| `gpt-5-nano` | `nano`, `gpt5` | OpenAI-powered free |
| `nemotron-3-super-free` | `nemotron` | Hit or miss |
| `qwen3.6-plus-free` | `qwen` | Intermittent |

All support streaming, tool calls, and system messages.

## Tool Configuration

### Cursor / Continue / Cline

- **Base URL**: `http://127.0.0.1:6446/v1`
- **API Key**: your proxy key (or `public` if no auth)
- **Model**: `deepseek-v4-flash-free` (or any alias)

### Claude Code

Claude Code uses the Anthropic Messages API natively. For now, use an OpenAI-compatible bridge or configure via:

```bash
# In Claude Code, use as custom provider
claude config set provider_base_url http://127.0.0.1:6446/v1
```

### OpenCode CLI

Add to `~/.config/opencode/opencode.json`:

```json
{
  "provider": {
    "free": {
      "name": "free",
      "type": "openai",
      "apiKey": "public",
      "baseURL": "http://127.0.0.1:6446/v1",
      "models": {
        "free/deepseek": {
          "id": "deepseek-v4-flash-free",
          "name": "free/deepseek"
        }
      }
    }
  }
}
```

### Any OpenAI SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:6446/v1",
    api_key="your-proxy-key"  # or "public" if no auth
)

response = client.chat.completions.create(
    model="deepseek-v4-flash-free",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## Deploy on VPS

```bash
# Build for Linux
GOOS=linux GOARCH=amd64 go build -o opencode-proxy .

# Copy and run
scp opencode-proxy user@vps:/home/user/
ssh user@vps './opencode-proxy -api-key "secure-key" -host 0.0.0.0'

# Or use systemd (create /etc/systemd/system/opencode-proxy.service)
```

systemd unit:

```ini
[Unit]
Description=OpenCode Zen Proxy
After=network.target

[Service]
ExecStart=/home/user/opencode-proxy -api-key "${PROXY_KEY}" -host 0.0.0.0
Restart=always
User=user
EnvironmentFile=/etc/opencode-proxy.env

[Install]
WantedBy=multi-user.target
```

## Local SSH tunnel

If you don't want to expose the port publicly:

```bash
ssh -L 6446:127.0.0.1:6446 user@your-vps
```

Then point your tools at `http://127.0.0.1:6446/v1`.

## License

MIT