Subpool

Enterprise AI subscription quota allocation and governance, self-hosted.

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.

Release pages publish the current version, immutable container image coordinates, source commit, and complete notes from GitHub Releases.

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 token telemetry per API key and subscription quota in provider-native units.
• Encrypt upstream credentials and never persist prompts, responses, or source code.

Architecture

For the internal protocol boundaries and request lifecycle, see Provider adapters.

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:8081 and sign in with the administrator credentials from .env. The employee API remains on http://localhost:8080.

Connect and use

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

For authorization methods, supported endpoints, and provider-specific limitations, see Provider accounts.

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