TokenHub is a private enterprise AI gateway with role-based workspaces for users, team leaders, and administrators.
| Login Console | Gateway Overview |
|---|---|
 |
 |
| API Documentation | Provider Channels |
 |
 |
| Model Catalog | Routing Policies |
 |
 |
| Usage Analytics | System Settings |
 |
 |
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 |
- 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 native systemd/launchd and Docker Compose options.
- PostgreSQL support for production deployments with connection pooling. See the PostgreSQL setup guide.
- Console language switching for English, Chinese, and Japanese.
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 configured 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=2See the deployment guide for configuration requirements, probes, and the real PostgreSQL E2E test.
Native Release on a Linux systemd host or macOS launchd host:
curl -fsSL https://raw.githubusercontent.com/astaxie/TokenHub/main/deploy/native/install.sh \
-o /tmp/tokenhub-install.sh
sudo bash /tmp/tokenhub-install.sh installDocker Compose from a repository checkout:
cp deploy/.env.example deploy/.env
# Replace every change-me value in deploy/.env with a strong secret.
./deploy/install.shOpen:
- Admin console:
http://localhost:3000 - Backend API:
http://localhost:8080 - Health check:
http://localhost:8080/healthz
Initial admin login:
- Username:
admin - Native install password: printed once by the installer
- Docker password: the value of
TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD
The native installer verifies Release checksums, installs a systemd or launchd service, and enables direct update, rollback, and restart controls in the version panel. The Docker deployment script validates production credentials, pulls published images, and starts the containers without building locally. Until the images are publicly available, a failed pull of the default latest tag automatically falls back to a local source build; an explicitly selected tag never does. Docker deployments keep the copyable update commands in the version panel. See the deployment guide for both modes.
Backend:
cd backend
go run ./cmd/tokenhubFrontend:
cd frontend
npm install
npm run devSmoke-test the model API with the included SDK example:
cd sdk
npm install
npm run test:deepseekTokenHub provides two opt-in workflows for AI-assisted changes:
| Workflow | Choose it for |
|---|---|
fast-dev |
Small, well-scoped, low-risk changes |
feature-dev |
Important features, user-visible or cross-component changes, public API or data-model changes, security-sensitive work, deployment changes, or architectural decisions |
Activate one by naming it in the request, such as Use fast-dev for this change. Without an explicit selection, the agent follows the normal repository guidance. The agent asks before switching workflows, and workflow selection does not authorize Git or pull-request actions. See AGENTS.md.
TokenHub is licensed under the Apache License 2.0.