underclass
underclass: an OpenAI-compatible pooling proxy that pins sessions to one account (prompt cache stays warm), cools quota-exhausted subscriptions until their wind
What is underclass?
underclass: an OpenAI-compatible pooling proxy that pins sessions to one account (prompt cache stays warm), cools quota-exhausted subscriptions until their window resets, and fails fast with the earliest Retry-After when the whole pool is dry.
Overview of underclass
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
What it is
underclass is an OpenAI-compatible pooling proxy that pools multiple ChatGPT/Codex, GitHub Copilot, and Claude Code subscriptions behind one endpoint. It pins sessions to one account (prompt cache stays warm), cools quota-exhausted subscriptions until their window resets, and fails fast with the earliest Retry-After when the whole pool is dry. The proxy listens on a local address and provides endpoints at /v1/responses, /v1/chat/completions, /v1/models (OpenAI surface), and /v1/messages (Anthropic surface). A web UI at the same origin offers account management, a catalog, a live request feed, and statistics.
Key features
- Sticky sessions: Requests carrying a prompt cache key always land on the same subscription, preserving upstream prompt caches.
- Health pool: Quota-exhausted accounts enter a cooling state and return to rotation automatically when their usage window resets.
- Fail-fast saturation: When every eligible account for a requested model is cooling, the proxy answers 429 plus the earliest Retry-After header.
- Two API surfaces: /v1/* endpoints speak OpenAI (for Codex and Copilot) and /v1/messages speaks the Anthropic Messages API (for Claude Code), routing each request only to backends that serve its surface.
- Token accounting: Each upstream attempt is recorded in SQLite with model, account, prompt cache key, and reported tokens; the admin page shows current-month totals and filters.
- Web UI and CLI tools: A web admin interface for account management, statistics, and a live request feed; the underclass CLI supports connect, reset, top, and stats commands.
Use cases
- Pooling multiple personal ChatGPT/Codex, GitHub Copilot, or Claude Code subscriptions into a single endpoint for use with any OpenAI-compatible client.
- Avoiding per-account quota exhaustion by automatically rotating accounts that are cooling off.
- Maintaining warm upstream prompt caches across requests by pinning sessions to a single subscription.
Getting started
shUNDERCLASS_PROXY_KEY=$(openssl rand -hex 32) UNDERCLASS_UI_TOKEN=$(openssl rand -hex 32) cargo run -- serveThen open the web UI, paste the admin token, and add accounts for ChatGPT/Codex, GitHub Copilot, or Claude Code.
License and pricing
This project is licensed under the MIT license. It is open source and free to use.
Based on the project's public README and repository metadata.