opencode-zen-proxy is a lightweight reverse proxy for opencode.ai. It provides dual-stack egress selection and cluster failover for opencode zen backend.
- Single-port dual-stack listener (IPv6 preferred → IPv4 fallback)
- Automatic egress IP probing and failure marking (cooldown)
- Cluster mode with private TLS+frame protocol for multi-node failover
- opencode CLI feature-header injection (User-Agent, x-opencode-client/project)
- Missing opencode tools auto-injection (bash, edit, glob, grep, read; chat vs responses format aware,
tools:nulltreated as empty) - Stream-to-nonstream conversion: downstream
stream:falseis forwarded upstream asstream:true, SSE is collected and reassembled into a single JSON response (opt-out via--no-stream-convert) - Session caching based on egress IP
- Inbound and outbound auth
- Custom DNS server and domain aliases (resolve alias IP, keep original Host/TLS)
go build -o opencode-zen-proxy ./cmd/zen-proxy| Parameter | Env | Default |
|---|---|---|
| PORT | PORT | 9000 |
| BACKEND | BACKEND | https://opencode.ai/zen/v1 |
| OUTBOUND_AUTH | OUTBOUND_AUTH | pass-through |
| INBOUND_AUTH | INBOUND_AUTH | disable |
| FWD_INBOUND | FWD_INBOUND | 0 |
| EGRESS_PREFER | EGRESS_PREFER | 6 |
| CLUSTER_TOKEN | CLUSTER_TOKEN | |
| CLUSTER_LISTEN | CLUSTER_LISTEN | |
| CLUSTER_JOIN | CLUSTER_JOIN | |
| PEERS | PEERS | |
| FAILOVER_ON | FAILOVER_ON | 429,502,503,504,timeout |
| CACHE_FILE | CACHE_FILE | logs/session-cache.json |
| IP_INTERVAL | IP_INTERVAL | 5m |
| DNS_SERVER | DNS_SERVER | system resolver |
| DNS_ALIAS | DNS_ALIAS | |
| NO_STREAM_CONVERT | NO_STREAM_CONVERT | 0 (flag: --no-stream-convert) |
curl -fsSL https://raw.githubusercontent.com/scyslz/opencode-forward/master/start.sh -o start.sh && bash start.sh startInteractive: when run from a terminal, prompts for listen port (default 9003), inbound auth, egress preference, DNS, cluster and model rewrite — Enter accepts defaults. The binary is downloaded automatically if missing.
Foreground with live logs:
bash start.sh runNon-interactive (pipes/cron skip prompts; use env vars):
PORT=9003 MODEL=gpt-5 bash start.sh start </dev/null| Command | Behavior |
|---|---|
./start.sh start |
Start in background, logs to file |
./start.sh run |
Start in foreground, logs streamed to terminal (also persisted) |
./start.sh stop |
Stop |
./start.sh restart |
Restart |
./start.sh status |
Show status + last 5 log lines |
Port conflict handling: if the port is held by an old instance of this binary it is stopped automatically and replaced; if held by another program the script exits with an error.
On /v1/chat/completions and /v1/responses outbound requests, any missing opencode tools (bash, edit, glob, grep, read) are injected; existing tools are never duplicated. Chat uses {type:function, function:{name,description,parameters}}, responses uses the flat {type:function, name,description,parameters} form.
When downstream requests stream:false on chat/responses paths, the proxy forwards stream:true upstream, buffers the SSE stream, and reassembles it into a single JSON response (choices/message (+tool_calls) for chat, terminal response object for responses). Reassembly failure falls back to passthrough. Disable with:
NO_STREAM_CONVERT=1 bash start.sh start
# or: ./opencode-zen-proxy 9000 https://opencode.ai/zen/v1 --no-stream-convertgo build -o opencode-zen-proxy ./cmd/zen-proxy
OUTBOUND_AUTH="Bearer sk-..." ./start.sh start
# or via scripts/
go build -o opencode-zen-proxy ./cmd/zen-proxy && ./scripts/start.sh startPublic listener:
CLUSTER_LISTEN=:9443 CLUSTER_TOKEN=s3 ./start.sh startPrivate joiner:
CLUSTER_JOIN=public:9443 CLUSTER_TOKEN=s3 ./start.sh startcmd/zen-proxy/main.go # entry, flag parsing, wiring
internal/proxy/ # HTTP reverse proxy & failover
internal/egress/ # dual-stack egress & probe
internal/cluster/ # private TLS+frame cluster protocol
internal/tunnel/ # tunnel persistence
internal/util/ # helpers, constants (UpstreamTimeout)
scripts/start.sh # service script (also ./start.sh shim)
configs/opencode-zen-proxy.service # systemd unit
legacy/ # previous flat files (reference only)
| Path | Description |
|---|---|
| cmd/zen-proxy/main.go | CLI args parsing & server |
| internal/proxy | HTTP reverse proxy & failover logic |
| internal/egress | dual-stack egress & probe manager |
| internal/cluster | private TLS+frame cluster protocol |
| internal/tunnel | tunnel persistence |
| internal/util | helpers |
| scripts/start.sh | unified service script |
| configs/opencode-zen-proxy.service | systemd unit |