Subpool

Subpool is a self-hosted control plane built by the gesta-run organization that lets enterprise teams pool authorized AI subscription and API accounts, distribute employee-specific keys, and monitor quota usage — all without storing conversation content. It is licensed under Apache 2.0 and deployed via Docker Compose, making it straightforward to run on any infrastructure that supports Docker Engine.

What It Is

Subpool sits between employees and upstream AI providers (currently OpenAI Codex and OpenAI-compatible accounts) as a managed gateway. Administrators combine multiple authorized subscription and API accounts into named pools, issue per-employee API keys scoped to those pools, and get a unified audit trail of input/output token usage per key. The service exposes an OpenAI-compatible API surface — including the Responses and Chat Completions endpoints — so existing tooling requires minimal reconfiguration.

Architecture and Stack

Subpool is a single Go 1.24 service with an embedded React 19 console and PostgreSQL 17 for persistence. The entire stack ships as a Docker Compose configuration that pulls a pre-built image from ECR Public, so no local build step is required for deployment. Key architectural properties include:

• Single binary control plane — Go backend with embedded React admin console
• PostgreSQL-backed state — shared authentication, rate-limit, assignment, and health state across replicas
• Encrypted credential storage — upstream provider credentials are encrypted at rest; prompts and responses are never persisted
• OpenAI-compatible API surface — GET/POST /v1/responses, POST /v1/chat/completions, GET /v1/models, plus health and metrics endpoints

How Quota Pooling Works

The core workflow centers on three objects: accounts, pools, and employee keys. Administrators connect Codex or OpenAI-compatible accounts (using device-code authorization for Codex subscriptions, which works on headless/remote servers without a localhost callback), group them into pools, and generate employee API keys tied to a pool. Subpool then:

• Prefers subscription capacity and falls back to paid API accounts automatically using the same employee key
• Monitors account health and remaining subscription capacity, tracking reset availability
• Rate-limits, expires, and revokes individual employee keys independently
• Keeps key-to-account assignments visible and auditable in the console

Fast mode for Codex subscription accounts is controlled centrally from the Accounts page, so employees do not need to configure it locally.

Deployment Model

Subpool is designed to run behind a reverse proxy that terminates TLS. The SUBPOOL_PUBLIC_URL environment variable sets the public origin. PostgreSQL, the credential encryption key, and the API key HMAC key must be backed up together. The .env.example file documents all configuration options. Codex clients are configured by editing a per-user config.toml file on Linux, macOS, or Windows to point at the Subpool URL with the employee API key as the bearer token.

Update: Subpool v0.1.0

The initial public release (v0.1.0) was published on September 4, 2026, shortly after the repository was created on September 2, 2026. The repository was last pushed to on September 11, 2026, indicating active early development. The project is tagged with topics including codex, claude-code, gateway, pooling, and ai-agents, signaling its intended use as a shared gateway for agentic AI coding tools in team environments.