CLIProxyAPI Deploy Package
Multi-provider proxy at cliproxy.fro.bot: Claude OAuth, Codex OAuth (OpenAI models), and an OpenAI-compatible OpenCode Go upstream. Docker Compose stack (Caddy + cli-proxy-api) on a DigitalOcean Droplet. CLI clients authenticate to the proxy with bearer API keys; Claude and Codex use stored OAuth tokens, while OpenCode Go uses its upstream API key. Consumer configuration and credential shapes are documented under OPENCODE_CONFIG and OPENCODE_AUTH_JSON shapes.
WHERE TO LOOK
Section titled “WHERE TO LOOK”| Task | Location | Notes |
|---|---|---|
| Config templates | config/config.yaml, config/Caddyfile |
Server template — runtime keys live on the droplet |
| Docker stack | docker-compose.yaml |
Caddy + cli-proxy-api, restart: unless-stopped, healthcheck on caddy probing /healthz |
| Provision droplet | server/provision-droplet.ts |
One-time. Refuses re-run on existing droplet without --force |
| Deploy updates | src/deploy.ts |
Preserves config.yaml, applies only field-scoped management changes |
| CLI commands | packages/cli/src/commands/cliproxy/ |
See packages/cli/AGENTS.md for command pattern |
| OpenCode Go policy | packages/shared/opencode-go/ |
settings.json and privacy-snapshot.json; eligibility logic in eligibility.ts |
| OpenCode Go procedures | docs/runbooks/cliproxy-opencode-go.md |
Enablement, rotation, emergency disable, re-enable, recovery, snapshot PR review |
DEPLOY FLOW
Section titled “DEPLOY FLOW”- Preflight (
preflightManagementKeyCheck): GET/v0/management/configwith the localCLIPROXY_MANAGEMENT_KEY. Aborts on 401/403 (key drift; a 403 whose body says “IP banned” aborts with a distinct source-IP-ban message, about 30 min, key may be fine), skips on missing key, fails on server errors. 10s fetch timeout. - Upload:
Caddyfile,docker-compose.yaml, andconfig.yaml(only if it does not exist on the server).--force-configoverrides the skip. The trackedpayload.overrideandclaudeblocks are first-deploy/bootstrap template fragments only; normal deploy never applies them to an existing runtime config. - Restart:
docker compose pull && docker compose up -d --wait --wait-timeout 90from/opt/cliproxy/, preceded by a best-effortdocker image prune -af(failure only warns). Compose waits for Caddy’s backend healthcheck before applying management-API changes; a failed healthcheck or 90-second timeout stops the deploy. - Model aliases (
applyOAuthModelAliasStep): read theoauth-model-aliasblock from the trackedconfig.yamland PUT it to/v0/management/oauth-model-alias(bare object), then read back and fail-closed on mismatch. Skips when the block is empty; throws when the block is present butCLIPROXY_MANAGEMENT_KEYis unset. Fork verification via/v1/modelsis best-effort (only whenCLIPROXY_API_KEYis set) and never fails the deploy. This never touches the runtimeapi-keys, so--force-configis not required. - OpenCode Go upstream (
applyOpenCodeGoStep): write and verify theopencode-goentry inopenai-compatibility. Its preflight (preflightOpenCodeGo) runs before any SSH. See OpenCode Go upstream. - Health gate: GET
/v0/management/configagain to confirm the proxy is up and the key still works.
All ssh/scp calls reuse one SSH connection (ControlMaster socket in a per-deploy temp dir) because the droplet’s UFW rate-limits new SSH connections (6 per 30 s); never add an ssh/scp call without the shared controlPath.
Critical: config.yaml on the server holds runtime API keys added via the management API. Unsafe template/SCP overwrite remains banned unless --force-config is explicit. Whole-document GET/PUT /v0/management/config.yaml is forbidden in unattended deploys, including preservation-verified exceptions. Managed config changes must use a field-scoped endpoint; if no field-scoped endpoint exists, automation stops and escalates rather than mutating the whole document. The one recorded exception is the openai-compatibility section: infra owns it outright and replaces the whole list through its own endpoint, behind the guards in OpenCode Go upstream. See docs/solutions/best-practices/cliproxy-management-api-field-apply-2026-06-20.md and the failed #1042 approach recorded in the plan.
Model aliasing: the oauth-model-alias block in the tracked config.yaml maps client-facing short Anthropic model ids to their dated upstream models with fork: true (both ids stay available). It is applied via the management API (step 4), not by uploading config.yaml — the block does not make --force-config safe.
DOCKER STACK
Section titled “DOCKER STACK”- Caddy: HTTPS termination, auto Let’s Encrypt.
restart: unless-stopped. Logs only/v0/management/*requests (JSON on stdout, credential headers deleted, credential query parametersvalue,api-key,codeandstateredacted in both this log and the default error logger) so a client sending bad management keys can be identified;json-filelogs are capped at 3 × 10 MB. Read it on the droplet:cd /opt/cliproxy && docker compose logs --no-log-prefix caddy | jq -Rr 'fromjson? | select(.logger == "http.log.access.log0") | [(.ts | todate), .request.client_ip, .request.method, .request.uri, .status, (.request.headers["User-Agent"][0] // "-")] | @tsv'— addand .status == 401to theselectfor bad-key callers. - cli-proxy-api:
eceasy/cli-proxy-api, pinned by tag and digest indocker-compose.yamland bumped by Renovate — read theimage:line for the current version rather than trusting a copy here. Debian bookworm base (v7.1.54+, no wget/curl).restart: unless-stopped. No container healthcheck — the upstream Debian image ships no probe tools; Caddy probes the backend instead (see below). - Healthcheck: lives on the
caddyservice, notcli-proxy-api. Caddy (alpine, has wget) runswget --spider -q http://cli-proxy-api:8317/healthzacross the compose network.docker compose up -d --waitgates on Caddy-healthy, which transitively proves the proxy is serving. - Volumes:
caddy_data,caddy_config,cliproxy_auth(OAuth tokens persist here across container recreates). - Env file:
MANAGEMENT_PASSWORDinjected from host.envinto the container. - Network: both services join the named bridge network
cliproxy(172.28.0.0/24). Caddy’s address is pinned to172.28.0.2indocker-compose.yaml; the network’sip_range(172.28.0.128/25) keeps dynamic allocation off that address, because Docker gives the first free subnet address to the first container started andcli-proxy-apistarts before Caddy.
Trusted proxy
Section titled “Trusted proxy”CLIProxyAPI bans by c.ClientIP() (gin). With the default trusted-proxies: [] that is Caddy’s address, so one client sending bad management keys bans every caller, including the deploy preflight. config/config.yaml therefore sets trusted-proxies: [172.28.0.2] — exactly Caddy’s pinned address, enforced by docker-compose.test.ts. The setting is read at startup only and has no management endpoint, so it applies with a cli-proxy-api restart. Deploy never uploads config.yaml over an existing server, so an existing server needs this one-off operator edit, run only after the deploy that pins Caddy to 172.28.0.2 has finished. Confirm that first:
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$(docker compose ps -q caddy)" # expect 172.28.0.2-
cd /opt/cliproxy -
cp config/config.yaml config/config.yaml.bak-$(date -u +%Y%m%dT%H%M%SZ) -
Add the key if it is absent.
yqis not on the stockdocker-20-04droplet image, so append; this runs only when no top-leveltrusted-proxies:exists and otherwise stops for a manual edit. It appends in place (>>), which keeps the file’s inode, comments and every other key, so the single-file bind mount stays valid:Terminal window if grep -q '^trusted-proxies:' config/config.yaml; thenecho 'trusted-proxies already present — edit it by hand, then continue at step 4' >&2else[ -z "$(tail -c1 config/config.yaml)" ] || echo >> config/config.yamlprintf "trusted-proxies: [172.28.0.2]\n" >> config/config.yamlfiDo not use
sed -iormv; they replace the inode and detach the bind mount. NeverPUT /v0/management/config.yaml. -
docker compose restart cli-proxy-api -
Verify. Health must return 200, then one request through Caddy must log your real address:
Terminal window curl -s -o /dev/null -w '%{http_code}\n' https://cliproxy.fro.bot/healthz # expect 200curl -s -o /dev/null https://cliproxy.fro.bot/v1/models # from your workstationdocker compose logs --since 2m --no-log-prefix cli-proxy-api | grep '"/v1/models"'The log line’s third
|-separated field is the client IP. It must be your workstation’s public address, not172.28.0.2(or the old172.18.0.3). A request that still shows a172.xaddress means the setting did not apply: check the key is top-level and the container restarted. To roll back,cpthe.bak-*file overconfig/config.yamland restart again.
MANAGEMENT API
Section titled “MANAGEMENT API”Verified endpoint surface (see apps/cliproxy/src/deploy.ts and packages/cli/src/commands/cliproxy/). Auth: x-management-key header only. The Authorization: Bearer header is for client API key auth (proxied requests to Claude), not management endpoints.
| Endpoint | Method | Body | Notes |
|---|---|---|---|
/v0/management/api-keys |
GET | — | Returns {"api-keys": [...]} (hyphenated) |
/v0/management/api-keys |
PUT | bare array [...] |
NOT wrapped in {api_keys: ...} |
/v0/management/api-keys?value=x |
DELETE | — | |
/v0/management/config |
GET | — | Read-only via HTTP |
/v0/management/config.yaml |
GET/PUT | complete raw YAML document | Whole-document access is forbidden in unattended deploys; no field-scoped endpoint exists for payload or claude, so automation must stop/escalate |
/v0/management/{field} |
PUT | {"value": <val>} |
Per-field updates: debug, request-retry, proxy-url, etc. |
/v0/management/oauth-model-alias |
PUT | bare object {claude: [...]} |
NOT wrapped in {value: ...} or {oauth-model-alias: ...} — those return 200 but store nothing. GET returns {"oauth-model-alias": {...}} |
/v0/management/openai-compatibility |
GET/PUT/PATCH | GET returns {"openai-compatibility": [...]}; PUT takes a bare array and replaces the whole list; PATCH takes {name, value: {disabled}} |
A bare [] PUT is accepted and clears the section. No endpoint creates a single entry. GET adds auth-index to each entry and returns api keys in clear |
/v0/management/usage-queue?count=N |
GET | — | v7: returns a bare JSON array of recent requests (not wrapped); /v0/management/usage was removed in v7 |
/v0/management/latest-version |
GET | — | Returns {"latest-version": "vX.Y.Z"} |
/healthz |
GET | — | Liveness endpoint, no auth; returns {"status":"ok"} |
v8 keeps every /v0/management path above and adds a separate /v8/management API. Stay on /v0: a v0 write re-saves config.yaml in the legacy layout. A v8-layout write migrates the file (nested server.*, access.api-keys, config-version: 8), and v7 cannot read the result.
v7 rollback
Section titled “v7 rollback”Before a major bump, take a cp -p backup of config/config.yaml. To roll back, revert the image pin, deploy, then confirm the live file has no config-version: 8. If it does, stop cli-proxy-api, cp the backup over config/config.yaml, and start it again. Leave the cliproxy_auth volume alone.
OPENCODE GO UPSTREAM
Section titled “OPENCODE GO UPSTREAM”The openai-compatibility section holds one entry, opencode-go, and infra owns the section outright. The policy is tracked in packages/shared/opencode-go/: settings.json (enabled, optional defaultProbeModel) and privacy-snapshot.json (reviewed privacy terms per model, refreshed by PR). Procedures live in docs/runbooks/cliproxy-opencode-go.md.
Eligibility. A model is exposed only when all of these hold:
- The snapshot entry is valid and records zero retention and no training.
- The model is in the live OpenCode Go model list.
- It has no region requirement. Region-gated models are never exposed; the parser gates a model on a restricted-models bullet, a
(limited regions)note, or a Privacy footnote that states a hosting location or a Global-region requirement. - Any agreement expiry is on or after today (UTC; the expiry day counts).
An invalid snapshot entry excludes only that model. These fail the deploy before any write: a snapshot that does not parse, a failed live-list fetch, and an empty eligible set. A live model missing from the snapshot is printed as excluded and the deploy carries on. The deploy excludes a model whose agreement has expired. Between deploys, the monitor flags an exposed model whose agreement has expired as privacy-noncompliant; it does not remove the model.
Guards. Before the write, a failure leaves the live proxy unchanged:
- Foreign entry: any live entry other than
opencode-gostops the deploy. - Never an empty list: a bare
[]PUT clears the section, so the client refuses to send one. - Disabled live entry: the deploy fails if the live entry is disabled while
settings.jsonsaysenabled: true. Follow the re-enable procedure in the runbook. - Collision: the deploy fails if an eligible bare or prefixed id is already served under another
owned_by.
After the write:
- Readback: the live entry must match the tracked one.
auth-indexis ignored;disableddefaults to false; models compare as a set. - Visibility: every eligible id must appear in
/v1/models, bare and prefixed, once each, withowned_by: opencode-go. - Smoke request: one non-streaming request at
max_tokens: 1on the probe model must return 2xx with ausage.opencode.billing_source.gois the plan. Any other present value is the credits fallback (Go usage window exhausted): the route works, so the deploy warns, naming the value, and passes. A missingbilling_sourceor a non-2xx answer raisesOpenCodeGoUnverifiedError. This request is billed to Go, or to credits during the fallback.
Any failure after the write raises OpenCodeGoUnverifiedError: “OpenCode Go entry APPLIED but UNVERIFIED (<stage>)”. The entry is live and unproven. Follow the runbook. The write stage covers the PUT and the disable PATCH: a transport error, a timeout, an HTTP 408 or a 5xx may follow a write the proxy already applied. A 4xx answer proves the proxy rejected the write and stays a plain failure. The management GET must hold an openai-compatibility field; an object without it fails before any write.
With enabled: false, the deploy PATCHes an existing entry to disabled: true, expects no Go ids in /v1/models and sends no smoke request. It needs no Go key.
The entry maps x-opencode-session: "$X-Opencode-Session", so the client’s session header reaches Go. Go answers 400 MissingSessionID without it. The monitor probe always sends the header, so that answer means the proxy dropped it: reason session-header-dropped, dead.
Secrets. CLIPROXY_OPENCODE_GO_KEY (new) and CLIPROXY_API_KEY (also used by the monitor) are repository secrets. The router’s caller job has no environment, so it cannot read Environment secrets (actions/runner#4453). It passes both explicitly to deploy-cliproxy.yaml. Only the deploy’s own HTTP calls use them; the environment given to ssh and scp never contains either.
Snapshot refresh. .github/workflows/opencode-go-privacy.yaml opens one PR on the branch opencode-go-privacy when a model’s privacy terms change. Auto-merge is off. A merged PR triggers the gated cliproxy deploy only. When upstream terms match main again, the next run closes the open PR with a comment and deletes the branch; the App token is minted for that case too.
OPENCODE_CONFIG AND OPENCODE_AUTH_JSON SHAPES
Section titled “OPENCODE_CONFIG AND OPENCODE_AUTH_JSON SHAPES”The proxy uses a single bearer key per consumer repo. The same key authenticates the anthropic, openai and opencode-go provider routes for that repo — there are no per-provider keys.
For proxy-routed providers configured via OPENCODE_CONFIG.provider.<name>.options.baseURL, the fro-bot/agent action does NOT require enable-omo: true to honor the auth.json. Source: fro-bot/agent@v0.44.3+ action.yaml:99-104. Librarian-verified 2026-05-25.
Three-provider OPENCODE_CONFIG:
{ "provider": { "anthropic": {"options": {"baseURL": "https://cliproxy.fro.bot/v1"}}, "openai": {"options": {"baseURL": "https://cliproxy.fro.bot/v1"}}, "opencode-go": {"options": {"baseURL": "https://cliproxy.fro.bot/v1"}} }}Three-provider OPENCODE_AUTH_JSON (same proxy key for every provider):
{ "anthropic": {"type": "api", "key": "<proxy-key>"}, "openai": {"type": "api", "key": "<proxy-key>"}, "opencode-go": {"type": "api", "key": "<proxy-key>"}}A repo lists only the providers it selected. Anthropic-only repos use the single-provider subset. A Go model id is opencode-go/<bare id>.
ANTI-PATTERNS
Section titled “ANTI-PATTERNS”- Never overwrite
config.yamlon the server without--force-config— it wipes runtime API keys (incident: 2026-04-06). - Never PUT
/v0/management/config.yamlfrom unattended deploy automation — whole-document replacement is forbidden. If a managed field lacks a field-scoped endpoint, stop and escalate upstream. - Field-scoped management only: follow the approved pattern in
docs/solutions/best-practices/cliproxy-management-api-field-apply-2026-06-20.md; preserve the runtime file by leaving unsupported managed fields unapplied rather than inventing a raw-config exception. - Never PUT an empty
openai-compatibilitylist — the server accepts a bare[]and clears the section. Never hand-add upstream entries: the deploy refuses to write while any entry other thanopencode-goexists. - Never re-run
provision-droplet.tsagainst an existing droplet without--force— it overwrites the management key. - Never use
Authorization: Bearerfor management endpoints — usex-management-key. - Never assume management API body shapes — empirically verified, not guessed (incident: 2026-04-07).
- v7 IP-bans the caller after 5 consecutive bad management-key attempts (~30 min). Management flows probe
/v0/management/configonce before issuing parallel calls so a wrong key costs a single failed attempt, never an escalating burst. - Never trust the whole subnet or the default network in
trusted-proxies— list only Caddy’s pinned address (172.28.0.2). Trusting a range lets any container on it spoof the client IP and dodge or redirect management bans. - Never commit
MANAGEMENT_PASSWORD— it lives in the droplet’s.envand the localCLIPROXY_MANAGEMENT_KEYsecret. - Never use
curlin healthchecks — onlywgetis in the Alpine base (Caddy image). The cli-proxy-api image (Debian bookworm, v7.1.54+) has no probe tools; healthcheck belongs on the caddy service.
- Secrets:
CLIPROXY_SSH_KEY,CLIPROXY_MANAGEMENT_KEY,CLIPROXY_DOMAINscoped to GitHub environmentcliproxy.DIGITALOCEAN_ACCESS_TOKEN,CLIPROXY_OPENCODE_GO_KEYandCLIPROXY_API_KEYare repo-level. - Local
.env:CLIPROXY_MANAGEMENT_KEYmust match the droplet’sMANAGEMENT_PASSWORD(set during provisioning, printed once). - Provisioning SSH key:
provision-droplet.tslooks up the DigitalOcean SSH key by name. Default isfro-bot-cliproxy; override withCLIPROXY_SSH_KEY_NAMEenv var. Shared helper lives inpackages/shared/server/droplet-helpers.ts. - Provisioning SSH auth: when
CLIPROXY_SSH_KEYis set,provision-droplet.tsmaterializes it to a0600temp key file and pins it with-i+IdentitiesOnly=yes(no ssh-agent needed; cleaned up after); when unset, it falls back to ssh-agent. - Run provisioning via the root wrapper:
bun run provision:cliproxy(loads the repo-root.env;bun run --cwd apps/cliproxy provisionwould miss it). - OAuth refresh: Claude OAuth tokens auto-refresh in
cliproxy_authvolume. Manual refresh:bunx @marcusrbrown/infra cliproxy login claude. - API key recovery: There is no recovery tooling. If keys are wiped, regenerate via
cliproxy keys addand redistribute.cliproxy config get --output backup.json(with0600perms) is the safest backup mechanism.
ANTHROPIC AUTH MONITOR
Section titled “ANTHROPIC AUTH MONITOR”The repository includes the CLI-only infra cliproxy monitor command and the scheduled workflow at .github/workflows/cliproxy-auth-monitor.yaml. The workflow runs at nominal 15-minute intervals (7,22,37,52 minutes past each hour); GitHub schedule delivery is best-effort. Manual dispatch accepts live, synthetic-dead, or synthetic-healthy validation. Scheduled runs always use live.
The monitor probes the Anthropic route with CLIPROXY_API_KEY, then reconciles one canonical GitHub issue and a dedicated outbound Discord webhook. GitHub calls go through a gh api subprocess parsed with Zod — never a direct REST fetch — and the GitHub token is passed only through the child process’s allowlisted environment, never argv, request body, or logs. An open issue represents dead provider auth; a closed or absent issue represents healthy auth. Discord messages are sent only on state transitions, with safe bounded summaries and a last-check heartbeat while an outage remains open. Public issue and Discord text is fixed and sanitized; raw provider responses and exception text never cross that boundary. Synthetic-mode Discord alerts are prefixed [synthetic test] so they are never mistaken for a real outage.
The probe classifies as dead (opening the issue and sending Discord) on HTTP 401, 503 auth_unavailable, or HTTP 400 model_not_found / “unknown provider for model” (reason provider-missing: no Anthropic provider is registered, so check /v1/models and run cliproxy login claude); any other non-2xx, timeout, or network failure is unknown and mutates nothing.
The dedicated label (cliproxy-auth-monitor / cliproxy-auth-monitor-test), not the hidden identity marker, is the trust anchor for issue adoption. An issue carrying the marker but not the label is ignored — the monitor never adopts it or restores the label onto it. An issue carrying the label but not the marker fails the run closed rather than being silently adopted. If a race produces more than one labeled+marked issue, resolution deterministically picks the lowest issue number so every later run converges on one canonical issue. GitHub’s Issues API has no atomic create-if-absent primitive, so a rare simultaneous first-create can still send a duplicate initial alert; deterministic selection prevents that race from causing persistent reconciliation failure, but it does not eliminate the one-time duplicate.
gh is a prerequisite only when running cliproxy monitor directly on a local machine (it must be installed and authenticated, or GITHUB_TOKEN must be set). The scheduled workflow already provides gh in its runner image and remains the preferred entrypoint for both live and synthetic validation.
OpenCode Go route
Section titled “OpenCode Go route”The same job probes a second route with the same CLIPROXY_API_KEY. Each route reconciles on its own, so a failure on one cannot block the other. The exit code reflects either.
- Probe line:
CLIProxy Go monitor probe: probe=<state> reason=<reason> at <timestamp>, printed before any reconciliation. - Billing line:
CLIProxy Go monitor billing: billing_source=<token>, printed right after the probe line when a 2xx named abilling_source. The token is the value if it matches[A-Za-z0-9._-]{1,32}, elseother. The status reader ignores it. - Issue: label
cliproxy-go-monitor, title “CLIProxy OpenCode Go route outage”. Its text points atdocs/runbooks/cliproxy-opencode-go.md. - Skips when
enabledis false insettings.json: no probe, no line, no issue and no alert. Onlylivevalidation probes Go. - Each probe lists
/v1/models, compares theopencode-gomodels it exposes with today’s eligibility, picks a probe model (defaultProbeModelwhen exposed, else the first exposed id), and sends one request atmax_tokens: 1with a freshx-opencode-session.
| Reason | State | Cause |
|---|---|---|
ok |
healthy | 2xx with billing_source: go |
billing-not-go |
dead | 2xx with a missing, null, non-string or empty billing_source |
billing-fallback |
unknown | 2xx with a present billing_source other than go: the Go usage window is exhausted and the account bills credits. The route works. cliproxy status warns and exits 0; the monitor opens no issue and sends no Discord |
provider-missing |
dead | No opencode-go models listed, or model_not_found |
privacy-noncompliant |
dead | An exposed model is not eligible |
quota-or-billing |
dead | HTTP 429 or 402 |
auth-401, auth-unavailable-503 |
dead | Proxy key rejected, or no auth available |
session-header-dropped |
dead | HTTP 400 MissingSessionID: the proxy stopped forwarding the session header the probe sends |
unrelated-http, timeout, network |
unknown | Any other failure |
A dead result opens the Go issue and sends Discord. A healthy result closes it. An unknown result changes nothing.
Setup and validation
Section titled “Setup and validation”-
Create a dedicated Discord incoming webhook for monitor alerts. Do not reuse the gateway’s inbound HMAC webhook. Test it with a fixed message, then store its URL as the repository secret
CLIPROXY_AUTH_MONITOR_DISCORD_WEBHOOKwithout logging or copying the URL into a command argument. -
Confirm the existing repository secret
CLIPROXY_API_KEYis available. The canonical proxy URL is non-secret and defaults tohttps://cliproxy.fro.bot. -
Run manual validation as the repository owner:
Terminal window gh workflow run cliproxy-auth-monitor.yaml -f validation=livegh workflow run cliproxy-auth-monitor.yaml -f validation=synthetic-deadgh workflow run cliproxy-auth-monitor.yaml -f validation=synthetic-healthyConfirm the live monitor summary proves the provider probe ran without creating an outage transition while auth is healthy. Synthetic validation uses the isolated test issue identity, never probes Anthropic, and never mutates production monitor state.
Go/no-go: enable unattended monitoring only when the workflow is on the default branch, issues: write is available, both repository secrets are present, the production canonical issue has at most one identity match, live validation is healthy, both synthetic transitions complete without touching production state, and GitHub workflow-failure notifications reach an operator.
Recovery and rollback
Section titled “Recovery and rollback”When the provider is dead, run bunx @marcusrbrown/infra cliproxy login claude. After the browser reaches the localhost connection-refused page, copy the full callback URL and paste it into the login prompt. Verify with bunx @marcusrbrown/infra cliproxy status, then trigger an immediate manual live monitor run rather than waiting for the next scheduled invocation:
gh workflow run cliproxy-auth-monitor.yaml -f validation=liveRecovery is complete when the provider is healthy, the canonical issue is closed, the recovery notification is delivered when required, and the healthy marker is persisted.
To roll back monitoring, disable or revert .github/workflows/cliproxy-auth-monitor.yaml, or rotate/remove CLIPROXY_AUTH_MONITOR_DISCORD_WEBHOOK if the destination is wrong or exposed. Preserve the canonical issue history. Rollback stops monitor activity; it does not restore Claude authentication.