Docker & Compose

TokenHub provides a Dockerfile for container builds and a Docker Compose file for local development with all dependencies.

Docker Image

Build

make package
# or
docker buildx build --load -t tokenhub .

The Dockerfile uses a multi-stage build:

Build stage: golang:1.24-alpine — compiles the Go binary and builds mdbook documentation
Runtime stage: alpine:3.21 — lightweight runtime with curl for health checks

The final image runs as a non-root tokenhub user.

Run

docker run -d \
  -p 8080:8080 \
  -e TOKENHUB_ADMIN_TOKEN="your-admin-token" \
  -v tokenhub_data:/data \
  tokenhub

The container expects:

Port 8080: HTTP server (binds all interfaces by default)
Volume /data: SQLite database persistence

Docker Compose

Full Stack

docker compose up -d

This starts:

Service	Port	Description
`tokenhub`	8080	TokenHub server
`temporal`	7233	Temporal server (gRPC)
`temporal-ui`	8233	Temporal Web UI

Services

TokenHub

tokenhub:
  image: tokenhub:latest
  ports:
    - "8080:8080"
  environment:
    - TOKENHUB_LISTEN_ADDR=:8080
    - TOKENHUB_DB_DSN=/data/tokenhub.sqlite
    - TOKENHUB_VAULT_ENABLED=true
    - TOKENHUB_VAULT_PASSWORD=${TOKENHUB_VAULT_PASSWORD}
    - TOKENHUB_ADMIN_TOKEN=${TOKENHUB_ADMIN_TOKEN}
  volumes:
    - tokenhub_data:/data
  restart: unless-stopped

Set TOKENHUB_VAULT_PASSWORD to auto-unlock the vault at startup (headless mode). If not set, unlock interactively via UI or tokenhubctl. Providers are loaded from ~/.tokenhub/credentials at startup, or registered at runtime via the admin API, tokenhubctl, or the admin UI.

Note: The TOKENHUB_DB_DSN should be a plain path (e.g., /data/tokenhub.sqlite) when using modernc.org/sqlite (the pure-Go driver). SQLite pragmas are applied programmatically, not via DSN query parameters.

Temporal

temporal:
  image: temporalio/auto-setup:latest
  ports:
    - "7233:7233"
  environment:
    - DB=sqlite
  volumes:
    - temporal_data:/etc/temporal/data

temporal-ui:
  image: temporalio/ui:latest
  ports:
    - "8233:8080"
  environment:
    - TEMPORAL_ADDRESS=temporal:7233

Environment File

Create a .env file for sensitive values:

TOKENHUB_ADMIN_TOKEN=your-secret-admin-token

Without Temporal

To run without Temporal:

docker compose up -d tokenhub

Or set TOKENHUB_TEMPORAL_ENABLED=false.

Provider Bootstrapping

Providers are loaded from ~/.tokenhub/credentials at startup. For Docker, mount the credentials file into the container or use the host path if running via Docker Compose with a volume mount. See Provider Management for the file format.

Health Check

The Docker health check uses the /healthz endpoint:

curl -f http://localhost:8080/healthz

Returns 200 when adapters and models are registered, 503 otherwise.

Data Persistence

All persistent data is stored in SQLite at the path configured by TOKENHUB_DB_DSN. In Docker, mount a volume to /data:

volumes:
  - tokenhub_data:/data

This persists:

Model and provider configurations
Vault salt and encrypted credentials
Request logs, audit logs, reward entries
API keys
Routing configuration
TSDB time-series data

Resource Requirements

TokenHub is lightweight:

Memory: ~50MB baseline, scales with request concurrency
CPU: Minimal (most time is spent waiting on provider APIs)
Disk: Depends on log retention; ~1MB per 10,000 requests

TokenHub Documentation