# Subpool

> A self-hosted, open-source control plane for allocating, governing, and auditing AI subscription quota across teams via pooled provider accounts and employee-specific API keys.

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.

## Features
- Pool authorized subscription and API capacity behind one managed endpoint
- Allocate employee-specific API keys across healthy provider accounts
- Monitor account health, remaining subscription capacity, and reset availability
- 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; never persist prompts, responses, or source code
- Device-code authorization for Codex subscriptions (works on headless/remote deployments)
- Centralized Fast mode control for Codex subscription accounts
- Health and metrics endpoints (/healthz, /readyz, /metrics)
- Embedded React admin console
- Docker Compose deployment with pre-built ECR Public image

## Integrations
OpenAI Codex, OpenAI-compatible APIs, PostgreSQL, Docker Compose, Docker Engine

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://github.com/gesta-run/subpool
- Documentation: https://github.com/gesta-run/subpool#readme
- Repository: https://github.com/gesta-run/subpool
- EveryDev.ai: https://www.everydev.ai/tools/subpool