English | 한국어

star-cliproxy

Turn the AI CLI subscriptions you already pay for (Claude Max, ChatGPT Pro, Gemini, Copilot, Grok, Antigravity) into one OpenAI-compatible API — no extra API keys, no per-token billing.

What is this?

star-cliproxy runs your installed AI CLIs as subprocesses and exposes them behind a single local OpenAI-compatible endpoint (/v1/chat/completions, /v1/messages, /v1/models, /v1/images/generations).

Point any OpenAI SDK at it — change only base_url, keep your code:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8300/v1", api_key="sk-proxy-...")
client.chat.completions.create(
    model="claude-sonnet",
    messages=[{"role": "user", "content": "Hello!"}],
)

Why star-cliproxy?

• 💸 Subscriptions, not API keys — bill against Claude Max / ChatGPT Pro / etc. instead of metered API tokens.
• 🔌 One endpoint, many backends — 5 built-in CLIs (Claude, Codex, Copilot, Antigravity, Grok) + any OpenAI-compatible HTTP server (vLLM, Ollama, MLX, LM Studio) + custom plugins.
• 🧭 Smart routing — alias-based model mapping with priority fallback chains, per-model provider overrides, and session reuse (codex exec resume).
• ⚙️ Multiple execution modes — cli, Claude Agent SDK, Codex app-server, and the new channel-worker bridge mode.
• 📡 Real SSE streaming — native NDJSON/JSONL event pipes, not fake post-hoc chunking.
• 📊 Full dashboard — live monitoring, Playground, request tracing with raw payloads, model/key management, rate limits, EN/KO + dark mode.
• 🔒 Hardened — Zod-validated config (fail-fast at startup), SHA-256 key auth, prompt/CLI injection guards, timing-safe comparisons, secret redaction.
• 🟣 Anthropic Messages API — /v1/messages lets native Claude Code / Anthropic SDK clients connect too.

Quick Start

⭐ Easiest: let an AI CLI set it up

This repo is structured so an agentic CLI can install and configure it for you. Open Claude Code or Codex in an empty folder and ask:

"Clone https://github.com/starhunt/star-cliproxy, read its README, then install dependencies, build, create config.yaml and .env (generate a strong ADMIN_TOKEN and an sk-proxy- prefixed PROXY_API_KEY), enable the providers I have installed, and start the backend and dashboard."

The agent runs the steps below and reports the URLs back to you.

Manual

git clone https://github.com/starhunt/star-cliproxy.git
cd star-cliproxy
npm install && npm run build

cp config.example.yaml config.yaml
cp .env.example .env
# .env: ADMIN_TOKEN + PROXY_API_KEY (must start with sk-proxy-)
node -e "console.log('ADMIN_TOKEN='+require('crypto').randomBytes(32).toString('hex'))"
node -e "console.log('PROXY_API_KEY=sk-proxy-'+require('crypto').randomBytes(24).toString('hex'))"

npm run dev            # backend API → http://localhost:8300
npm run dev:dashboard  # dashboard   → http://localhost:5300

Prerequisites: Node.js 20+ and at least one authenticated CLI. Run each CLI once on its own first to finish login.

Supported Providers

Antigravity and Grok compatibility

Both providers accept reasoning_effort. Their current CLI range is low, medium, or high, so xhigh and max requests are safely normalized to high. The model-mapping editor and Playground expose this setting.

On the first startup after upgrading, built-in legacy mappings are migrated automatically: old Antigravity display labels become stable model-family slugs, grok-build routes to grok-4.5, and the removed default grok-composer mapping is disabled. User-created custom mappings are not overwritten. Because CLI catalogs can vary by account and release, check agy models and grok models after upgrading the CLIs.

Usage

OpenAI SDKs (Python/TS), curl, and native Claude Code all work — just set the base URL and an sk-proxy- key.

# OpenAI-compatible (streaming)
curl http://localhost:8300/v1/chat/completions \
  -H "Authorization: Bearer sk-proxy-..." -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet","messages":[{"role":"user","content":"Hello"}],"stream":true}'

# Native Claude Code → cliproxy (Anthropic Messages API)
ANTHROPIC_BASE_URL=http://localhost:8300 ANTHROPIC_API_KEY=sk-proxy-... claude

Models are exposed as aliases (e.g. claude-sonnet, gpt-5) mapping to a provider + real model. Manage mappings, providers, and keys from the dashboard or the Admin API.

Execution Modes

Dashboard (:5300)

Live request monitoring & trends, Playground, model-mapping editor, provider config (execution mode + bridge controls), API keys, rate limits, and debug payload capture (CLI args + raw stdout, copy-as-curl). EN/KO, dark/light.

Configuration

• config.yaml — providers, model mappings, rate limits, validation (Zod-validated at startup). See config.example.yaml.
• .env — ADMIN_TOKEN, PROXY_API_KEY.
• Custom providers auto-load from plugins/.

Documentation

Plugin Guide · Provider Architecture · Session Reuse · Image Generation

Security

SHA-256 API-key auth · prompt-injection & CLI-injection prevention · timing-safe comparisons · Zod config validation · debug-log redaction with retention. Never commit .env.

License

MIT. Subscriptions and CLI usage remain subject to each provider's terms of service.

Built with Claude Code.