Requirements
Prerequisites for self-hosting Tokamak
Check these requirements before installing Tokamak.
Software
| Requirement | Minimum version | Notes |
|---|---|---|
| Docker | 24.x | Docker Engine or Docker Desktop |
| Docker Compose | v2 | Included with Docker Desktop |
| Git | Any | For cloning the repository |
| Make | Any | The documented workflow uses make targets |
Hardware
These are guidance figures rather than measured limits — the Compose stack sets no CPU or memory constraints.
Development:
| Resource | Suggested minimum |
|---|---|
| CPU | 2 cores |
| RAM | 4 GB |
| Disk | 10 GB |
Production:
| Resource | Recommended |
|---|---|
| CPU | 4+ cores |
| RAM | 8+ GB |
| Disk | 50+ GB (depends on media storage and request archives) |
External requirements
| Requirement | Required | Notes |
|---|---|---|
| PostgreSQL 18 with pgvector | Yes | Bundled as the api-db container (pgvector/pgvector:pg18) |
| Redis | No | Optional. Bundled as the redis container; core uses it only to share Claude Pool credential affinity across replicas (REDIS_URL) |
| At least one LLM provider API key | Yes | Configured through the admin API once the stack is up |
| S3-compatible storage | Production only | For media and request archives. MinIO works. |
| An OIDC provider (Keycloak) | No | Optional. Not started by the Compose stack — point at an existing installation, or use preview login in a local development environment. |
Database schemas
Core, auth and billing each own a schema inside the same PostgreSQL database and create it on first boot. The schema names are configurable via TOKAMAK_CORE_DB_SCHEMA, TOKAMAK_AUTH_DB_SCHEMA and TOKAMAK_BILLING_DB_SCHEMA; the pgvector extension is installed automatically by core's first migration.