TokenHub

TokenHub is a private enterprise AI gateway with role-based workspaces for users, team leaders, and administrators.

English | 简体中文 | 日本語

Screenshots

Login Console	Gateway Overview
API Documentation	Provider Channels
Model Catalog	Routing Policies
Usage Analytics	System Settings

Designed Around Three Roles

TokenHub separates everyday model usage, team governance, and platform administration so enterprise users see the workflows that match their responsibility.

Role	Workspace Focus	Guide
User	Find available models, create project-scoped API keys, call the model API, and review personal usage	User Guide
Team Leader	Manage project spaces, project members, project keys, team reports, and project cost attribution	Team Leader Guide
Administrator	Configure providers, model catalog, routing policies, identity sources, RBAC, audit, and cost controls	Administrator Guide

Platform Capabilities

• OpenAI-compatible model APIs: /v1/chat/completions, /v1/responses, /v1/embeddings.
• Provider channels for OpenAI-compatible, Azure OpenAI, Anthropic, Gemini, DeepSeek, Qwen, local vLLM/Ollama, and custom upstreams.
• Model catalog and routing policies with priority, weight, failover order, and route health diagnostics.
• Project-scoped key management with team ownership, member permissions, quotas, and concurrency controls.
• Usage analytics and request logs attributed to user, project, team, model, and cost center.
• Identity source configuration for OAuth/OIDC enterprise sign-in, plus RBAC and audit trails.
• Clean console with compact role-aware navigation, global search, light/dark mode, and split-view API documentation.
• SQLite-first private deployment with Docker Compose support.
• PostgreSQL support for production deployments with connection pooling. See the PostgreSQL setup guide.
• Console language switching for English, Chinese, and Japanese.

Multi-Instance Architecture

The default installation starts one frontend and one backend with SQLite. For horizontal scaling, use deploy/docker-compose.remote-postgres.yml: it places Nginx in front of scalable frontend and backend replicas and stores shared state in a remote PostgreSQL database. A SQLite file must never be shared by multiple backend replicas.

In multi-instance mode:

• Nginx load-balances console, API, and health-check traffic across healthy replicas.
• Backend replicas keep durable configuration, OAuth sessions, quota buckets, audit data, cluster locks, and in-flight concurrency leases in PostgreSQL.
• Lease expiry and ownership decisions use the PostgreSQL clock, avoiding early takeover caused by clock skew between hosts. Heartbeats cancel work when lease ownership is lost.
• The mounted model catalog is synchronized on every backend startup; a cluster lease serializes the idempotent synchronization across replicas.
• Coordination failures release provider capacity without incorrectly marking a healthy model provider as failed.

All backend replicas must use the same TOKENHUB_SECRET_KEY. Size TOKENHUB_DB_MAX_OPEN_CONNS per replica so the combined connection pool stays below the PostgreSQL limit.

docker compose --env-file deploy/.env \
  -f deploy/docker-compose.remote-postgres.yml up -d \
  --scale tokenhub-backend=3 \
  --scale tokenhub-frontend=2

See the deployment guide for configuration requirements, probes, and the real PostgreSQL E2E test.

Quick Start

cp deploy/.env.example deploy/.env
# Replace every change-me value in deploy/.env with a strong secret.
./deploy/install.sh

Open:

• Admin console: http://localhost:3000
• Backend API: http://localhost:8080
• Health check: http://localhost:8080/healthz

Initial admin login:

• Username: admin
• Password: the value of TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD

The deployment script validates production credentials before building. It reports each unsafe variable without printing secret values. If Compose fails because a backend container created or restarted by that attempt is unhealthy, the script automatically shows only that attempt's recent backend logs.

Local Development

Backend:

cd backend
go run ./cmd/tokenhub

Frontend:

cd frontend
npm install
npm run dev

Smoke-test the model API with the included SDK example:

cd sdk
npm install
npm run test:deepseek

Documentation

• Documentation home
• User Guide
• Team Leader Guide
• Administrator Guide
• 简体中文文档
• 日本語ドキュメント

Star History

License

TokenHub is licensed under the Apache License 2.0.