subpool

Subpool is a self-hosted control plane for allocating, governing, and auditing AI subscription capacity across teams. Administrators combine authorized subscription and API accounts into pools, distribute employee-specific keys, monitor remaining quota, and expose one consistent API without storing conversation content.

Features

• Pool authorized subscription and API capacity behind one managed endpoint.
• Allocate employee-specific keys across healthy provider accounts.
• Monitor account health, remaining subscription capacity, and reset availability.
• Keep key-to-account assignments visible and auditable.
• Prefer subscription capacity and fall back to paid API accounts with the same employee key.
• Rate-limit, expire, and revoke employee access independently.
• Expose OpenAI-compatible Responses and Chat Completions APIs.
• Track aggregate input and output usage per API key.
• Encrypt upstream credentials and never persist prompts, responses, or source code.

Architecture

Subpool is a single Go service with an embedded React console and PostgreSQL persistence.

Quick start

Requires Docker Engine and Docker Compose.

cp .env.example .env

# Generate independent secrets and place them in .env.
openssl rand -base64 32
openssl rand -base64 32
openssl rand -hex 32

docker compose up -d

Replace every replace-with-* value. Docker Compose pulls the latest published Subpool image from ECR Public; no local image build is required. Open http://localhost:8080 and sign in with the administrator credentials from .env.

Connect and use

1. Open Accounts and connect a Codex or OpenAI-compatible account.
2. Create a pool and add the account.
3. Create an employee API key for the pool.

Codex subscriptions use device-code authorization. Copy the one-time code from Subpool, continue to OpenAI, and confirm it there. This works on remote and headless deployments without a localhost callback or an extra exposed port. Device-code login must be enabled in ChatGPT security or workspace settings.

Fast mode is controlled per Codex subscription account from the Accounts page. Subpool enforces the selected mode, so employees do not need to configure Fast mode in Codex.

After creating an employee API key, configure Codex on each user's machine to route requests through Subpool. Edit the user-level Codex configuration file:

• Linux: /home/<username>/.codex/config.toml (or ~/.codex/config.toml)
• macOS: /Users/<username>/.codex/config.toml (or ~/.codex/config.toml)
• Windows: C:\Users\<username>\.codex\config.toml (or %USERPROFILE%\.codex\config.toml)

Create the .codex directory and config.toml file if necessary. Replace https://subpool.example.com with your Subpool URL and sk-example-not-a-real-key with the employee API key created in Subpool.

model = "gpt-5.6-sol"
model_provider = "subpool"
model_reasoning_effort = "xhigh"

[model_providers.subpool]
name = "Subpool"
base_url = "https://subpool.example.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-example-not-a-real-key"
requires_openai_auth = false
supports_websockets = true

[features]
responses_websockets_v2 = true

Save the file, then restart Codex so the new provider and WebSocket settings are loaded. Codex subscription accounts use a dedicated upstream WebSocket, while OpenAI-compatible accounts use the existing HTTP/SSE bridge.

Available endpoints include GET/POST /v1/responses, POST /v1/chat/completions, GET /v1/models, GET /healthz, GET /readyz, and GET /metrics.

Deployment notes

• Terminate TLS at a reverse proxy and set SUBPOOL_PUBLIC_URL to the public origin.
• Back up PostgreSQL together with SUBPOOL_CREDENTIAL_KEY and SUBPOOL_API_KEY_HMAC_KEY.
• Use PostgreSQL for shared authentication, rate-limit, assignment, and health state across replicas.

See .env.example for configuration options.

Development

make compose-dev-up
make web-install
make dev

compose.dev.yaml builds subpool:local from the current source tree instead of pulling the published image.

Before opening a pull request:

make web-test
make web-build
go test ./...

Terms

Subpool is licensed under the Apache License 2.0. It is independent and self-hosted. Use only accounts you are authorized to manage, and review each upstream provider's terms before sharing access.