Skip to content

Tighten the Workers-only README to match what is merged #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
playgrndlabs-bot merged 1 commit into from
Oct 29, 2026
Merged

Tighten the Workers-only README to match what is merged #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Two ways to install. Both are free and open source, with the same dashboard; sub
| Install | Your Cloudflare plan | What runs | Deploy |
|---|---|---|---|
| **Container** | Workers Paid (Cloudflare bills $5/month; Containers need it) | The latest CPA release in a container, with its official dashboard | <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/PlaygrndLabs/sub2api"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" width="240"></a> |
| **Workers-only** | Workers Free | Our container-free TypeScript rewrite of CPA with CPA's own dashboard (Claude and ChatGPT logins, API keys, format translation) | <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/PlaygrndLabs/sub2api/tree/main/free"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" width="240"></a> |
| **Workers-only** | Workers Free | Our container-free TypeScript rewrite of CPA with CPA's own dashboard (Claude, ChatGPT and Kimi logins, API keys, any client format to any provider) | <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/PlaygrndLabs/sub2api/tree/main/free"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" width="240"></a> |

## Why

Expand Down
34 changes: 12 additions & 22 deletions free/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,24 @@

A container-free version of sub2api that runs on Cloudflare's **free** Workers plan. It is a TypeScript rewrite of CPA (CLIProxyAPI), not CPA itself, and serves **CPA's own dashboard** (Cli-Proxy-API-Management-Center) through a port of CPA's v8 management API. So both installs look and work the same in the browser.

It covers **Claude, ChatGPT (Codex) and Kimi subscriptions** and **API keys** for Claude, Gemini (including Interactions), Vertex AI, Codex, xAI and any OpenAI-compatible provider, plus **Vertex AI service accounts**. More OAuth providers and format translation come in later phases.
It covers **Claude, ChatGPT (Codex) and Kimi subscriptions**, **Vertex AI service accounts**, and **API keys** for Claude, Gemini (including Interactions), Vertex AI, Codex, xAI and any OpenAI-compatible provider.

- CPA's dashboard, downloaded at build time from the latest panel release (pin one with `PANEL_VERSION`, and its checksum with `PANEL_SHA256`).
- Claude and ChatGPT (Codex) OAuth logins from the dashboard's **OAuth Login** page (the same PKCE flows as CPA, Claude Code and the Codex CLI), with tokens refreshed automatically.
- Kimi logins (kimi.com or kimi.ai) through Kimi's device sign-in, as in CPA. Claude Code and both OpenAI formats reach Kimi untranslated, and Gemini clients through Anthropic Messages: ask for a Kimi model such as `kimi-k3` or `kimi-k2.8`. Requests name this gateway, as CPA's name CLIProxyAPI.
- Several logins per provider, used in turn, with a failing or rate-limited Claude or ChatGPT login skipped for the next. Upload, download, disable, edit and delete them under **Auth Files**, in CPA's auth-file format, so files move between the two installs.
- Claude and ChatGPT (Codex) logins from the dashboard's **OAuth Login** page (the same PKCE flows as CPA, Claude Code and the Codex CLI), Kimi logins through Kimi's device sign-in, and Vertex service accounts from a Google Cloud key file. Tokens refresh automatically.
- Several logins per provider, used in turn. Upload, download, disable, edit and delete them under **Auth Files**, in CPA's auth-file format, so files move between the two installs.
- CPA's YAML config, edited in the **Config Panel**. Client API keys live in `access.api-keys`, as in CPA.
- `POST /v1/messages` and `POST /v1/messages/count_tokens`, streamed straight through to Anthropic.
- API-key providers added under **AI Providers** (CPA's `api-keys` config): Claude, Gemini, Gemini Interactions, Vertex AI, Codex, xAI and OpenAI-compatible endpoints such as OpenRouter. Model aliases, `prefix/model` routing, priorities, key weights (with the `weighted-round-robin` strategy) and excluded models work as in CPA, and a request moves on to the next key when one is rate limited or failing.
- Codex CLI through a ChatGPT login, on `/backend-api/codex/responses` or `/v1/responses`. Other OpenAI Responses clients work too: their requests are adapted to what the ChatGPT endpoint takes, and a non-streaming request gets the final response as JSON.
- Claude Code on an OpenAI-compatible key (OpenRouter and the like): ask for one of the provider's model aliases and the request goes out as Chat Completions, with the answer streamed back as Anthropic events, following CPA's Claude-to-OpenAI translator.
- Vertex AI service accounts imported under **OAuth Login** (a Google Cloud key file and a region, as in CPA). The Durable Object signs in to Google with the key and refreshes the token hourly. Gemini clients use them as they are, and other clients through the translators below.
- xAI keys take OpenAI Responses and Chat clients as they are, and Claude Code through the Claude-to-Responses translator below (for example `ANTHROPIC_MODEL=grok-4.5`).
- Claude Code on a ChatGPT login or a Codex API key: ask for a ChatGPT model (for example `ANTHROPIC_MODEL=gpt-5.6-sol`) and the request is translated to OpenAI Responses and the answer streamed back as Anthropic events, with thinking, tool calls and images, following CPA's Claude-to-Codex translator.
- Claude Code on a Gemini API key: ask for a Gemini model (for example `ANTHROPIC_MODEL=gemini-2.5-flash`) and the request goes out as Gemini `generateContent`, with thinking, tool calls and images, following CPA's Claude-to-Gemini translator. Unlike CPA, Google's default safety filters stay on; a blocked answer ends with a `refusal` stop reason.
- OpenAI Chat clients (Cursor, Cline, the OpenAI SDKs and the like) on a Claude API key: ask `/v1/chat/completions` for a Claude model and the request goes out as Anthropic Messages, with reasoning effort, tool calls, images, files and prompt caching, and the answer comes back as Chat Completions, following CPA's OpenAI-to-Claude translator. Claude logins aren't offered to these clients, since without CPA's cloaking Anthropic accepts a subscription token from Claude Code only.
- OpenAI Responses clients on a Claude API key, the same way, following CPA's Responses-to-Claude translator: reasoning, function and custom tool calls, images and files, streamed as Responses events or returned whole.
- Gemini clients (the Gemini SDKs, Gemini CLI with an API key) on a Claude API key, following CPA's Gemini-to-Claude translator: function calls and results, images and files, thinking settings, streamed with or without `?alt=sse` or returned whole.
- OpenAI Chat, Responses and Gemini clients on any other provider too (a Gemini key, an OpenAI-compatible key, a Codex key or a ChatGPT login): the request is translated to Anthropic Messages and on to the provider's format, and the answer back the same way.
- Each client talks in its own format: Anthropic (`/v1/messages`), OpenAI Chat (`/v1/chat/completions`), OpenAI Responses (`/v1/responses`) Gemini (`/v1beta/models/{model}:generateContent`) and Gemini Interactions (`/v1beta/interactions`, served by Interactions keys only, as in CPA). A request goes to a provider that takes the same format, apart from the translations above.
- Model lists as in CPA: `GET /v1/models` (OpenAI's shape, or Anthropic's for Claude Code and the Anthropic SDKs), `GET /v1beta/models` and `GET /v1beta/models/{model}` list every model across the logins and API keys, and so does the dashboard's **Available Models**. The Codex CLI gets its own catalog format (`/v1/models?client_version=`, see `model_catalog_url` below): ChatGPT models come with Codex's own prompts and settings from CPA's templates, and the rest with a short prompt and without the features only ChatGPT's backend has. A login or key with no model list of its own lists CPA's catalog for its provider, and a ChatGPT login the catalog for its plan. The catalog is refreshed from CPA's model catalog every three hours, with a built-in copy as fallback; it only decides what is listed, never where a request goes.
- Usage and logs as in CPA: each login and API key shows its success and failure counts and the last 200 minutes in 10-minute buckets, and with **Logging to file** on, the **Logs** page shows a line per API request (the last 2,000). Lines hold the time, status, latency, client IP, path, provider and model, never request bodies or keys. Records are sent to the Durable Object in batches a few seconds apart.
- CPA's routing across logins and keys, set in the `routing` config section: the `round-robin` (default), `weighted-round-robin` and `fill-first` strategies within the highest priority, failover to the next login or key, extra rounds with `retry.request-retry`, `max-retry-credentials` and `max-retry-interval`, and CPA's cooldowns: a rate-limited credential rests until the provider's stated reset (Retry-After, Anthropic's rejected-window reset, ChatGPT's usage-limit reset, Gemini's retry delay) or on CPA's 1 s to 30 min backoff, a refused or unpaid one for 30 minutes, a missing model for 12 hours, and a transient error for 60 seconds (`cooldown.transient-error-cooldown-seconds`). `cooldown.disable-cooling`, and per-key or per-login `disable-cooling`, `request-retry`, `priority`, `weight` and `prefix`, work as in CPA. **Auth Files** shows each login's cooldowns, and the reset button clears them. Each isolate shares its cooldowns through the Durable Object, so other isolates see them within a minute. A request makes at most 10 upstream attempts and waits at most 2 minutes in all, to stay inside the free plan's limits. With a single Claude login and nothing else, Claude Code requests still stream straight through. Kimi logins and Vertex service accounts fail over and cool down one by one too, like Claude and ChatGPT logins.
- API-key providers under **AI Providers** (CPA's `api-keys` config), with model aliases, `prefix/model` routing, priorities, weights and excluded models as in CPA.
- Each client talks in its own format: Anthropic (`/v1/messages`), OpenAI Chat (`/v1/chat/completions`), OpenAI Responses (`/v1/responses`, or `/backend-api/codex/responses` for the Codex CLI), Gemini (`/v1beta/models/{model}:generateContent`) and Gemini Interactions (`/v1beta/interactions`, Interactions keys only, as in CPA).
- Any client reaches any provider. A request the provider can't take as sent is translated, following CPA's translators, with thinking, tool calls, images and streaming. Claude Code and Codex CLI requests to their own logins pass through untouched.
- Claude logins serve Claude Code only: without CPA's cloaking, Anthropic accepts a subscription token from Claude Code alone. Other clients use Claude models through a Claude API key.
- Model lists as in CPA: `GET /v1/models`, `GET /v1beta/models` and the dashboard's **Available Models** list every model across logins and keys, from CPA's model catalog (refreshed every three hours). The Codex CLI gets its own catalog format (see `model_catalog_url` below).
- CPA's routing, set in the `routing` config section: `round-robin`, `weighted-round-robin` and `fill-first`, failover to the next login or key, retries, and CPA's cooldowns for rate-limited or failing credentials, honouring the provider's stated reset. **Auth Files** shows each login's cooldowns. A request makes at most 10 upstream attempts within 2 minutes, to stay inside the free plan's limits.
- Usage and logs as in CPA: success and failure counts per login and key, and with **Logging to file** on, a **Logs** line per API request (the last 2,000), never with request bodies or keys.
- Everything is stored in one SQLite-backed Durable Object, which the free plan includes.

Claude Code and Codex CLI request bodies are never parsed, so a Worker spends well under 1 ms of its 10 ms CPU budget even on a 600 KB Claude Code request (see the CPU test in `test/app.test.ts`). Requests that need a model rewritten or a body adapted are parsed once. Translated requests cost the most, about 4 to 6 ms for a 600 KB conversation; very long conversations translated can run past the free plan's 10 ms, which the Container install doesn't have.
Claude Code and Codex CLI request bodies are never parsed, so a Worker spends well under 1 ms of its 10 ms CPU budget even on a 600 KB Claude Code request (see the CPU test in `test/app.test.ts`). Requests that need a model rewritten or a body adapted are parsed once. Translated requests cost the most, about 4 to 6 ms for a 600 KB conversation; very long translated conversations can run past the free plan's 10 ms, which the Container install doesn't have.

Not included yet: Gemini and other OAuth logins, and CPA's per-request detail logs. Deliberately left out: CPA's request cloaking and TLS fingerprint spoofing. Clients other than Claude Code may be refused by Anthropic when they use a subscription token.
Not included yet: Gemini and other OAuth logins, and CPA's per-request detail logs. Deliberately left out: CPA's request cloaking and TLS fingerprint spoofing. Unlike CPA, Google's default safety filters stay on for Gemini.

## Try it

Expand Down
Loading