Skip to main content
Works on CORE Cloud (via workspace BYOK) and on self-hosted deployments (via env or BYOK). If you already pay for Claude Max (Anthropic) or a ChatGPT plan that includes Codex, you can point CORE at your subscription instead of buying separate API credits. CORE never touches the subscription’s OAuth tokens directly — a small proxy service (running on infrastructure you control) sits between them and translates OpenAI-compatible requests into whatever the subscription CLI expects.
The proxy runs on infrastructure you control (laptop, tailnet host, small VPS, Vercel AI Gateway). CORE — cloud or self-hosted — just makes OpenAI-compatible API calls to whatever URL you give it. OAuth tokens for your subscription stay on your side.
Subscription plans are licensed for interactive use. Providers can rate-limit or revoke OAuth tokens they detect being used as a headless backend for a hosted service. Fine for personal self-host on your own laptop or VPS; risky if you’re serving other users or a public product. If in doubt, use real API keys.

​
How it works

CORE talks to CLIProxyAPI as if it were an OpenAI-compatible API. CLIProxyAPI holds your subscription OAuth tokens and translates each request into the native protocol (Anthropic messages, ChatGPT Codex, Gemini, etc.). Multiple subscriptions can be logged into the same proxy.

​
Where to run the proxy

The proxy needs to be reachable from the machine running CORE. Pick whichever matches your setup:
  • Self-hosted CORE on your laptop / server → run the proxy on the same host (or same docker network). Local http://localhost:8317 works.
  • CORE Cloud, personal use → run the proxy on your laptop + expose it via a Cloudflare Tunnel, tailnet, ngrok, or a $5 VPS. CORE Cloud can’t reach localhost on your machine directly.
  • CORE Cloud, no self-hosting → Vercel AI Gateway is a first-party proxy for Claude Max that requires no self-hosting at all; skip to Alternatives for the URL.

​
1. Boot the proxy

CORE ships a compose recipe at hosting/cliproxy/ in the repo. If you’re on CORE Cloud, clone just to get the compose file:
Self-hosted users already have the repo checked out — cd hosting/cliproxy && docker compose up -d. The compose file exposes:
  • Main API on ${CLIPROXY_PORT:-8317} — this is what CORE calls
  • OAuth callback ports (1455 Codex, 54545 Claude, 8085 Gemini, 51121 Qwen, 11451 iFlow) bound to 127.0.0.1 so they aren’t network-exposed
A persistent named volume cli_proxy_auth:/root/.cli-proxy-api stores OAuth tokens across container rebuilds.

​
2. Set your proxy API key

Edit hosting/cliproxy/config.yaml:
Generate one with openssl rand -hex 32. This is your proxy’s key — completely unrelated to any subscription. You’ll paste this same string into CORE later. Restart the container after editing:

​
3. Log in to your subscription

Run the proxy’s login command for each subscription you want to use. The -no-browser flag prints a URL — paste it into your laptop browser, sign in, and approve. Claude Max / Claude Pro
ChatGPT Plus / Pro / Business (Codex)
Others: --gemini-login, --qwen-login, --iflow-login.
If the exact binary path fails, run docker compose exec cli-proxy-api ls -la /CLIProxyAPI to find the actual binary, or use docker compose run --rm cli-proxy-api --claude-login to invoke via the image entrypoint.
Verify the login worked by listing available models:
You should see the model IDs your subscription can serve — e.g. claude-sonnet-4-6, claude-haiku-4-5-20251001, gpt-5.5, etc. Note the exact IDs: some (like claude-sonnet-4-6) work in short form, others (like claude-haiku-4-5-20251001) require the date-stamped version.

​
4. Wire the proxy into CORE

Recommended: workspace BYOK (works on both cloud and self-hosted, no restart, scoped to one workspace). Self-hosted deployments can also set it globally via env.

​
Workspace BYOK (cloud + self-hosted)

In the CORE webapp, open Workspace Settings → Models → API Keys, click + Add API key, choose OpenAI, and fill in:
  • Base URL — where CORE reaches the proxy:
    • CORE Cloud → your public/tunnel URL, e.g. https://cliproxy.mytunnel.trycloudflare.com/v1
    • Self-hosted, both on your laptop → http://localhost:8317/v1
    • Self-hosted CORE in Docker + proxy on the same host → http://host.docker.internal:8317/v1 (Mac) or http://cli-proxy-api:8317/v1 if they share a docker network
  • API key: the same random string you put in config.yaml
Save. Then in the Models section pick a tier (Default / Low / High), choose Enter model ID…, and type a router string prefixed with openai/ — e.g. openai/claude-sonnet-4-6. The openai/ prefix forces CORE to route through the openai provider path (which now honors the workspace’s proxy URL); the model id after the slash is what gets sent to CLIProxyAPI.

​
Self-hosted, globally via env

Third-party proxies generally don’t implement the OpenAI Responses API — OPENAI_API_MODE=chat_completions is required.

​
5. Pick your model IDs

Grab exact IDs from GET /v1/models (step 3). Suggested defaults: Low and High fall back to Default when empty — you only need to fill them in if you want a different model at those tiers (cheap for background work, expensive for reasoning-heavy paths).

​
Structured outputs & tool calling

Under the hood, CORE routes structured-extraction calls (memory ingestion, label classification, etc.) via OpenAI-compatible tool calling when a workspace proxy is configured. Claude’s structured outputs enforce grammar-constrained sampling on tool args, so the model physically can’t respond with prose refusals like “there’s nothing to extract” — it will call the tool with empty arrays. This is why the proxy path is reliable even for empty or trivial content. If tool calling fails for any reason (proxy translation bug, network hiccup), CORE falls back to prompt-based JSON extraction with a tolerant parser, and finally to an empty-schema coercion — chain of three so ingestion never blocks on a proxy quirk.

​
Combined with local embeddings

Pair this with the local embeddings backend for a fully key-free self-host:
No Anthropic API key, no OpenAI API key, no separate embedding server. Just your subscription.

​
Troubleshooting

unknown provider for model X from the proxy — you haven’t authenticated the subscription that serves that model. Run the matching --*-login command. Incorrect API key provided from platform.openai.com — CORE isn’t sending through the proxy. Check that your Workspace Settings → OpenAI row has both a Base URL and an API key saved, and that your model id starts with openai/. 502 from the proxy with a model id that’s not in the served list — some model IDs need the date-stamped form (e.g. claude-haiku-4-5-20251001 not claude-haiku-4-5). Re-check the exact IDs from GET /v1/models. Callback port already in use during login — the proxy publishes callback ports on 127.0.0.1 only. If another local process is using 54545 / 1455, stop it first (or edit the compose file to remap).

​
Alternatives

The hosting/cliproxy/ compose targets CLIProxyAPI. Other options that expose the same OpenAI-compatible surface:
  • Vercel AI Gateway — first-party pass-through for Claude Max via ANTHROPIC_BASE_URL. Requires a Vercel account, but zero self-hosting.
  • ai-cli-proxy-api — variant that supports Factory and Amp CLIs alongside ChatGPT Plus/Pro and Claude Pro/Max.
  • ai-sdk-provider-claude-code — direct Vercel AI SDK provider (not proxy) — would require adding a new provider block in CORE’s model resolver rather than the drop-in URL swap this doc describes.
Anything that exposes an OpenAI-compatible /v1/chat/completions endpoint works with CORE via the same Base URL + API key wire-up.