CLIProxyAPI OpenCode Go Upstream
CLIProxyAPI serves OpenCode Go models next to Claude and GPT. The cliproxy deploy owns one upstream entry, opencode-go, in the openai-compatibility section. A reviewed privacy snapshot decides which models the entry exposes. This runbook covers enablement, key rotation, emergency disable, re-enable, recovery from a failed deploy, snapshot PR review and limits. For the deploy flow, guards and monitor reasons, see apps/cliproxy/AGENTS.md.
The tracked policy is in packages/shared/opencode-go/: settings.json (enabled, defaultProbeModel) and privacy-snapshot.json.
Enablement order
Section titled “Enablement order”-
Create the
CLIPROXY_OPENCODE_GO_KEYrepository secret from your OpenCode Console API key. Read the value from stdin. Never pass it as an argument:Terminal window pbpaste | tr -d '\n' | gh secret set CLIPROXY_OPENCODE_GO_KEY --repo marcusrbrown/infraCLIPROXY_API_KEYmust also exist as a repository secret. The monitor already uses it. -
Merge the change.
-
Approve the cliproxy gate.
-
Verify:
-
The deploy log ends with
OpenCode Go applied and verified: <N> models visible, smoke request billed to Go. -
The Go ids are listed:
Terminal window bunx @marcusrbrown/infra cliproxy models opencode-go -
A dispatched monitor run prints both probe lines, each with
probe=healthy reason=ok:Terminal window gh workflow run cliproxy-auth-monitor.yaml -f validation=liveCLIProxy auth monitor probe: probe=healthy reason=ok at <timestamp>CLIProxy Go monitor probe: probe=healthy reason=ok at <timestamp> -
A real task with tool calls runs on a Go model through a scratch repo’s proxy key. Wire the repo with
bunx @marcusrbrown/infra agent setup --providers anthropic,opencode-go --model opencode-go/<id>, then run an agent task that edits a file. -
A gateway workspace run on a Go model succeeds. See “OpenCode Go through the proxy” in
apps/gateway/AGENTS.md. -
A Claude request on the same scratch repo key still reaches Claude.
-
If the deploy ends with “APPLIED but UNVERIFIED”, go to Applied but unverified.
Merge before deploy
Section titled “Merge before deploy”The merge triggers the cliproxy deploy, which waits at the approval gate. Until you approve it, the live proxy has no Go entry. A monitor run in that window reports provider-missing and opens a Go issue. The issue closes on the first healthy probe after the deploy. No action is needed beyond approving the gate.
Go key rotation
Section titled “Go key rotation”-
Create a new key at the OpenCode Console.
-
Update the repository secret:
Terminal window pbpaste | tr -d '\n' | gh secret set CLIPROXY_OPENCODE_GO_KEY --repo marcusrbrown/infra -
Redeploy and approve the gate:
Terminal window bunx @marcusrbrown/infra cliproxy deployThe deploy writes the new key into the entry and sends a smoke request.
-
Revoke the old key at the Console after the deploy succeeds.
Emergency disable without a deploy
Section titled “Emergency disable without a deploy”Use this when Go must stop serving now.
-
Send the management PATCH. Load the management key into an environment variable, then give it to
curlon stdin so it never appears in argv:Terminal window read -rs CLIPROXY_MANAGEMENT_KEY && export CLIPROXY_MANAGEMENT_KEYprintf 'x-management-key: %s\n' "$CLIPROXY_MANAGEMENT_KEY" | curl -sS -X PATCH \https://cliproxy.fro.bot/v0/management/openai-compatibility \-H @- -H 'Content-Type: application/json' \-d '{"name":"opencode-go","value":{"disabled":true}}' -
Confirm the models left
/v1/models. The list must be empty within seconds:Terminal window bunx @marcusrbrown/infra cliproxy models opencode-go -
Set
"enabled": falseinpackages/shared/opencode-go/settings.jsonin a PR. Merge it and approve the gate. The deploy leaves the entry disabled and checks that no Go model is served.
Merge step 3 promptly. A deploy that runs while the live entry is disabled and enabled is still true fails with the disabled-entry error.
The Go issue stays open as the record until the PR merges. After that the monitor skips Go, and you close the issue by hand.
Then take the extra step that matches the cause:
- Suspected key leak: disable, then rotate. Revoke the old key at the Console. Create a new key and update the repository secret (Go key rotation, steps 1 and 2). Skip the redeploy: the re-enable deploy writes the new key.
- Privacy or billing problem: disable only. Do not rotate. Fix the cause first, then re-enable.
Re-enable
Section titled “Re-enable”Use this after an emergency disable, or when the deploy fails with The live "opencode-go" entry is disabled but settings.json says enabled.
-
Fix the cause. For a leak, the new key must already be in the repository secret.
-
Set
"enabled": trueinpackages/shared/opencode-go/settings.jsonin a PR. Merge it and leave the cliproxy gate pending. -
Enable the live entry:
Terminal window read -rs CLIPROXY_MANAGEMENT_KEY && export CLIPROXY_MANAGEMENT_KEYprintf 'x-management-key: %s\n' "$CLIPROXY_MANAGEMENT_KEY" | curl -sS -X PATCH \https://cliproxy.fro.bot/v0/management/openai-compatibility \-H @- -H 'Content-Type: application/json' \-d '{"name":"opencode-go","value":{"disabled":false}}' -
Approve the gate at once. The deploy rewrites the entry with the current key and eligible models, then verifies it.
Until the deploy finishes, the entry serves its old model list. Do not wait between steps 3 and 4.
Applied but unverified
Section titled “Applied but unverified”The error reads OpenCode Go entry APPLIED but UNVERIFIED (<stage>). The write reached the proxy, or may have, and the outcome is not proven. The entry is live and unproven. Do not assume Go routing works.
| Stage | What failed | Check |
|---|---|---|
write |
The write request got no usable answer: a network error, a timeout, an HTTP 408 or a 5xx. The proxy may have applied it. A 4xx answer is a plain failure, not this stage. | Read GET /v0/management/openai-compatibility. If the entry is there, check it as for read-back. Then rerun the deploy. |
read-back |
The live entry differs from the tracked one. The error names the fields. | Read GET /v0/management/openai-compatibility. Compare the named fields. |
visibility |
An eligible id is missing or listed twice, or an ineligible id is served. The error names the ids. | bunx @marcusrbrown/infra cliproxy models opencode-go |
smoke request |
The proxy returned a non-2xx status, or a 2xx carried no billing_source. |
Check the status in the error. 401 or 403 means a bad key. 429 or 402 means the plan limit or balance. |
post-write check |
A network or parse error after the write. | Rerun the deploy and read the error. |
Then:
- A present
billing_sourceother thangois not this error. It is the credits fallback: the Go usage window is exhausted and the account bills credits. The deploy warns and passes, and the monitor stays silent. It is not an outage. Check Console usage. Disable via Emergency disable (disable only) only if the value is unexpected and the Go window is not exhausted. - Otherwise fix the cause and rerun
bunx @marcusrbrown/infra cliproxy deploy. The deploy writes the entry again and repeats every check. - If the entry cannot be fixed, disable it.
The monitor flags the same state with a Go issue.
Session header dropped
Section titled “Session header dropped”The monitor reports session-header-dropped when the probe gets HTTP 400 MissingSessionID. The probe always sends x-opencode-session, so the proxy stopped forwarding it. Go rejects every request without it, so real traffic fails too.
- Read
GET /v0/management/openai-compatibility. Theopencode-goentry must holdheaders: {"x-opencode-session": "$X-Opencode-Session"}. - If the header mapping is missing or different, rerun
bunx @marcusrbrown/infra cliproxy deploy. The deploy writes the tracked entry. - If the mapping is present, the proxy build no longer applies it. Roll back the CLIProxyAPI image or disable the entry (Emergency disable).
The Go issue closes on the next healthy probe.
Snapshot refresh PR review
Section titled “Snapshot refresh PR review”The OpenCode Go Privacy workflow runs daily and on dispatch. It opens or updates one PR on the branch opencode-go-privacy when a model’s privacy terms change. A change to the source commit alone opens no PR.
Review the PR before you merge:
- Open the compare link in the PR body. It spans the old and new source commits of the OpenCode docs repository.
- Check each added, removed and changed model against the privacy table in that diff. The table and its footnotes are the authority, not the parsed JSON.
- Check every new model for zero retention, no training, no region requirement and any agreement expiry.
Merge rules:
- Auto-merge stays off.
- Merging triggers the gated cliproxy deploy. Approve the gate.
- Between the merge and the approved deploy, a model that lost eligibility is still served. The monitor reports it as
privacy-noncompliant. Approve the deploy promptly, or disable.
If upstream reverts the change before you merge, the next daily run finds that the terms match main again. It closes the open PR with a comment, then deletes the opencode-go-privacy branch. A PR on that branch from a fork is left alone. Do not merge a PR that the workflow closed. A later change to the terms opens a new PR. If the run cannot reach the PR list or the close step fails, the run fails: close the PR by hand and delete the branch.
A run that cannot parse the table fails and opens no PR. The deploy keeps the reviewed snapshot.
Limitations
Section titled “Limitations”- Expiry: the deploy enforces agreement expiry. Between deploys, the monitor flags an expired model as
privacy-noncompliant. - Region-gated models: never exposed. A Privacy footnote that states a hosting location (
Hosted in <place>.) or requires Global regions gates the model, whether or not a restricted-models bullet also lists it. - Plan limits: a 429 or 402 alerts as dead with reason
quota-or-billing. The Go issue closes on the next healthy probe. - Credits fallback: a 2xx with a present
billing_sourceother thangoisunknown/billing-fallback. The monitor printsCLIProxy Go monitor billing: billing_source=<token>, opens no issue and sends no alert.cliproxy statuswarns and exits 0. An open Go issue stays as it is until a healthy probe closes it. - Probe allowance: each probe is one
max_tokens: 1request. The monitor sends 96 a day. The deploy sends one per run, andcliproxy statussends one per run. - Management key: anyone holding it can read the Go key in clear. It already reads the downstream api keys in clear.