{"slug": "underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account", "title": "Underclass: An OpenAI-compatible pooling proxy that pins sessions to one account", "summary": "Developer Geoffrey Huntley released underclass, an OpenAI-compatible local proxy that pools multiple ChatGPT/Codex and GitHub Copilot subscriptions behind a single endpoint at /v1/responses, /v1/chat/completions, and /v1/models. The proxy pins sessions to one subscription for 24 hours to keep upstream prompt caches warm, moves quota-exhausted accounts (429 or usage-limit responses) into a cooling state until retry-after, and returns 429 with the earliest reset time when all accounts for a requested model are cooling. It is written in Rust and run via `cargo run -- serve`, with accounts added through a web UI using ChatGPT/Codex OAuth device flow or GitHub Copilot device flow.", "body_md": "**A local proxy that pools multiple ChatGPT/Codex and GitHub Copilot subscriptions behind one OpenAI-compatible endpoint.**\n\n```\n                       ┌────────────────────────────────────┐\n                       │            underclass              │\n                       │                                    │\n opencode ────────────►│  /v1/responses                     │\n (any OpenAI-compatible│  /v1/chat/completions              │────► chatgpt.com\n  client)              │  /v1/models                        │      (N Codex subs,\n                       │                                    │       OAuth device flow)\n web UI ◄─────────────►│  sticky sessions · health pool     │\n (accounts, catalog,   │  fail-fast saturation · tracing    │────► api.githubcopilot.com\n  live request feed)   │                                    │      (M Copilot subs,\n                       └────────────────────────────────────┘       GitHub device flow)\n```\n\nOne subscription runs out of quota? It leaves rotation until its window resets — and comes back on its own. Sessions stay pinned to one subscription so upstream prompt caches stay warm. When *everything* is exhausted, the proxy fails fast with the earliest reset time instead of hanging.\n\nSubscription-based model access has a per-account quota. One account is a ceiling; twenty accounts are a pool. underclass turns a pile of personal subscriptions into a single durable endpoint that behaves like one well-provisioned provider:\n\n- **No client changes** — the surface is plain`/v1/*` ; point opencode (or anything OpenAI-compatible) at it.\n- **No quota whiplash** — exhausted accounts cool down and recover automatically; clients never see account churn.\n- **No cache waste** — sessions are sticky, so the upstream prompt cache keeps working across turns.\n\n```\nUNDERCLASS_PROXY_KEY=\"$(openssl rand -hex 32)\" \\\nUNDERCLASS_UI_TOKEN=\"$(openssl rand -hex 32)\" \\\ncargo run -- serve\nunderclass listening on http://127.0.0.1:8080\nweb ui: http://127.0.0.1:8080/\n```\n\nKeep the generated values in a password manager or runtime secret file; underclass\nnever writes them to diagnostics. Open the web UI and paste the value supplied as\n`UNDERCLASS_UI_TOKEN`.\n\n1. Open the web UI and paste the configured admin token.\n2. Click **Add account** → pick*ChatGPT / Codex* or*GitHub Copilot* → enter the device code at the shown URL. The account is labeled automatically with the account's email or username.\n3. Repeat for every subscription you want in the pool.\n4. Point opencode at the pool:\n\n```\ncargo run -- connect\nopencode --provider underclass --model underclass/gpt-5.5\n```\n\n`underclass connect` writes the provider block and credentials into your global opencode config (`~/.config/opencode/opencode.json{,c}` + `auth.json`), idempotently and with backups. Re-run it any time; `--remove` undoes it.\n\n- **Sticky sessions.** Requests carrying`prompt_cache_key` /`promptCacheKey` (opencode sends the session ID when configured with`setCacheKey: true` ) always land on the same subscription. Bindings live for 24h, survive restarts, and rebind preferentially within the same backend when an account cools.\n- **Health pool.** A quota response (`429` /usage-limit bodies) moves an account to*cooling* until`retry-after` (or a per-backend default). 401s trigger one token refresh + retry, then the account needs re-login. Cooling accounts stay configured and return to rotation automatically.\n- **Fail fast.** If every account eligible for the requested model is cooling, the proxy answers`429` +`Retry-After` = earliest reset. No queuing.\n- **Flat pool.** Codex and Copilot accounts compete by least-in-flight, filtered by per-backend model catalogs. Unknown model IDs pass through to Codex so new models work without proxy changes.\n- **Pre-first-byte failover only.** Once a stream starts, upstream errors pass through — no silent re-send of half-finished turns.\n\nDesign decisions and their trade-offs live in [`docs/adr/`](https://github.com/ghuntley/underclass/blob/main/docs/adr) — start with [ADR 0010](https://github.com/ghuntley/underclass/blob/main/docs/adr/0010-unprefixed-routing-flat-pool.md) for the routing model.\n\nOptional `~/.config/underclass/config.toml`:\n\n| key | default | meaning | \n|---|---|---|\n| `bind` | `127.0.0.1:8080` | listen address | \n| `proxy_key` | minted on first run | bearer key clients must send to `/v1/*` | \n| `ui_token` | minted on first run | admin token for the web UI + `/admin/api/*` | \n| `codex_cooldown_secs` | `1800` | cooling window when upstream omits `retry-after` | \n| `copilot_cooldown_secs` | `1800` | same, for Copilot | \n\nEnvironment overrides: `UNDERCLASS_BIND`, `UNDERCLASS_PROXY_KEY`, `UNDERCLASS_UI_TOKEN`. For testing against a mock upstream: `UNDERCLASS_CODEX_UPSTREAM`, `UNDERCLASS_COPILOT_UPSTREAM` (default to the real endpoints).\n\nState (credentials, sticky bindings, model catalog, minted keys) lives in `~/.local/share/underclass/pool.db`. Delete it to start fresh.\n\n```\nunderclass serve [--bind ADDR]\nunderclass connect [--base-url URL] [--api-key KEY] [--model MODEL]\n                   [--project] [--no-default-model] [--dry-run] [--remove]\n```\n\n`connect` targets the global opencode config by default; `--project` writes `./.opencode/opencode.json` instead. `--dry-run` prints the merged documents without writing.\n\n| route | auth | purpose | \n|---|---|---|\n| `POST /v1/responses` | proxy key | Responses API, streamed through to the pool | \n| `POST /v1/chat/completions` | proxy key | Chat Completions, same | \n| `GET /v1/models` | proxy key | union catalog with merged limits | \n| `GET /` | none | web UI | \n| `GET /admin/api/state` | admin token | accounts, catalog, last 200 requests | \n| `POST /admin/api/flows` | admin token | start a device-flow onboarding | \n| `GET /admin/api/flows/{id}` | admin token | poll an onboarding flow | \n| `POST /admin/api/accounts/{id}/enable | disable | relogin` | \n| `DELETE /admin/api/accounts/{id}` | admin token | remove from pool | \n| `GET | PUT /admin/api/catalog/{backend}` | admin token | \n| `GET /admin/api/client-key` | admin token | retrieve the proxy key for `connect` | \n\nEvery response carries `x-request-id`; logs are JSON (` RUST_LOG` filters, `--log-format json|pretty`) and each request logs the account (label) that served it.\n\nThe catalog is data, not code: seeded with the Codex families (`gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex-spark`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`) and Copilot's live `/models` list. Edit it in the UI or via the admin API; routing eligibility and the opencode model block follow it. See [ADR 0007](https://github.com/ghuntley/underclass/blob/main/docs/adr/0007-config-driven-model-catalog.md).\n\nThe repository is a Nix flake: it exposes the CLI as a package/app and the devenv development shell as `devShells.default`.\n\nRun the proxy without installing:\n\n```\nnix run github:ghuntley/underclass -- serve\n```\n\nInstall it into your profile:\n\n```\nnix profile install github:ghuntley/underclass\n```\n\nUse the devenv shell (Rust toolchain, cargo) for development:\n\n```\nnix develop --no-pure-eval\ncargo test\n```\n\n`--no-pure-eval` is required for the devenv shell (devenv inspects the working directory; this matches devenv's own flake template). The package and app outputs are pure — `nix run` and `nix profile install` need no flags.\n\nLong-term devenv users can keep using `devenv shell` / `devenv test` directly — `nix develop` and `devenv shell` activate the same `devenv.nix`.\n\nAdd underclass to your flake inputs and import its module:\n\n```\n{\n  inputs.underclass.url = \"github:ghuntley/underclass\";\n\n  outputs =\n    { nixpkgs, underclass, ... }:\n    {\n      nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {\n        system = \"x86_64-linux\";\n        modules = [\n          underclass.nixosModules.default\n          {\n            services.underclass = {\n              enable = true;\n              bindAddress = \"127.0.0.1:8080\";\n              environmentFile = \"/run/secrets/underclass.env\";\n              settings = {\n                codex_cooldown_secs = 1800;\n                copilot_cooldown_secs = 1800;\n              };\n            };\n          }\n        ];\n      };\n    };\n}\n```\n\nThe runtime environment file can provide credentials without placing them in the Nix store:\n\n```\nUNDERCLASS_PROXY_KEY=sk-underclass-...\nUNDERCLASS_UI_TOKEN=...\n```\n\nThe service uses a dynamic user, persists its database in `/var/lib/underclass`, binds to localhost by default, and leaves the firewall closed. Set `services.underclass.openFirewall = true` only when intentionally binding beyond localhost.\n\nThe flake also exports `overlays.default`. Validate the module and its QEMU machine test with:\n\n```\nnix build .#checks.x86_64-linux.underclass-module\nnix build .#checks.x86_64-linux.underclass-vm\n```\n\nNotes:\n\n- The package builds from the committed `Cargo.lock` ; dependency versions are pinned there.\n- `nix build` skips`cargo test` because the property tests compile the Hegel engine as a build step, which needs network access that the Nix sandbox denies. CI runs the full suite via devenv (see`.github/workflows/ci.yml` ).\n\n- Access/refresh tokens, authorization headers, and prompt bodies are **never** logged.\n- Account labels (email/username) appear in logs and the UI by design; raw UUID account IDs are truncated.\n- `auth.json` written by`connect` uses`0600` . Never commit`pool.db` or`*.bak` .\n- The proxy binds to localhost by default; put it behind a tunnel only if you understand the exposure.\n- OAuth tokens rotate: every Codex refresh persists the new refresh token immediately.\n\n```\ncargo build\ncargo test        # 43 unit tests + 8 Hegel property tests + e2e suite\n```\n\nTesting is two-tier: plain unit tests for exact behavior (headers, merges, redaction), and [Hegel](https://hegel.dev) property tests over the pure pool core — stickiness stability, health-state invariants, saturation minimums, TTL/cap bounds. The core (`src/pool.rs`, `src/health.rs`) is synchronous with an injected clock; async lives only at the edges. New backends implement the `provider::Backend` trait and register — nothing else changes.\n\nAgent conventions and the ADR policy are in [`AGENTS.md`](https://github.com/ghuntley/underclass/blob/main/AGENTS.md). Architecture decision records: [`docs/adr/`](https://github.com/ghuntley/underclass/blob/main/docs/adr).\n\n```\nsrc/\n  main.rs      bootstrap, router, background tasks\n  config.rs    TOML + env config\n  models.rs    domain types (Account, status, catalog, log entries)\n  store.rs     SQLite persistence (accounts, bindings, catalog, config)\n  pool.rs      pure pool core: stickiness, eligibility, selection\n  health.rs    quota classification, retry-after parsing\n  provider.rs  Backend trait\n  codex.rs     ChatGPT/Codex backend (device flow, refresh, headers)\n  copilot.rs   GitHub Copilot backend (device flow, catalog, headers)\n  tokens.rs    single-flight token refresh\n  proxy.rs     /v1/* handlers, failover, streaming\n  logging.rs   structured logs, correlation IDs, redaction\n  ui.rs        admin API\n  ui.html      embedded single-page web UI\n  cli.rs       `connect` verb, JSONC-safe opencode config merge\ntests/\n  properties.rs  Hegel property tests over the pure core\n  e2e.rs         full-pool story against a mock upstream\n```\n\n", "url": "https://wpnews.pro/news/underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account", "canonical_source": "https://github.com/ghuntley/underclass", "published_at": "2026-09-20 11:24:22+00:00", "updated_at": "2026-09-20 11:52:52.199332+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "developer-tools", "ai-infrastructure"], "entities": ["underclass", "OpenAI", "ChatGPT", "Codex", "GitHub Copilot", "Geoffrey Huntley", "opencode", "Rust"], "alternates": {"html": "https://wpnews.pro/news/underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account", "markdown": "https://wpnews.pro/news/underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account.md", "text": "https://wpnews.pro/news/underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account.txt", "jsonld": "https://wpnews.pro/news/underclass-an-openai-compatible-pooling-proxy-that-pins-sessions-to-one-account.jsonld"}}