Sub2API

Sub2API is an AI API gateway platform that distributes and manages the quotas of AI product subscriptions. Users reach upstream providers through platform-issued API keys, while the gateway takes care of authentication, billing, load balancing and request forwarding.

This template deploys the complete stack:

• sub2api — Go backend with the embedded Vue admin dashboard, exposed on your public domain.
• postgresql — PostgreSQL 18 on a persistent volume: upstream accounts, keys, usage logs and billing.
• redis — Redis 8 on a persistent volume: cache, queues and distributed scheduling state.

Getting started

1. Deploy, then open https://<your-domain>.
2. Log in with the admin email and password shown in the Sub2API service Instructions section (admin@sub2api.local and the auto-generated ADMIN_PASSWORD by default; both also appear in the service's variables).
3. Add upstream accounts (Claude, OpenAI, Gemini, Grok) under Accounts, attach them to groups, and create API keys for your users.
4. Point clients at the gateway:
   • OpenAI / Codex compatible: https://<your-domain>/v1
   • Anthropic / Claude Code compatible: https://<your-domain>
   • Gemini compatible: https://<your-domain>

Notes

• Both databases are reachable only over the project's private network: this template disables TCP port forwarding. Enable it from each service's Networking tab if you want to connect with a local client.
• Important service instructions:
  • Connection strings for PostgreSQL and Redis are visible in each service's Instructions tab.
  • /app/data on the Sub2API service holds config.yaml (generated once by AUTO_SETUP) and application logs; it must stay mounted for the generated JWT_SECRET to survive restarts.
  • Updating the image (weishaw/sub2api:latest) keeps the data: the app detects the existing configuration instead of running setup again. You can also upgrade in-place from the dashboard's Check for Updates button.
• 2FA is off by default. To enable it, set TOTP_ENCRYPTION_KEY on the Sub2API service to a fixed key of 64 hex characters (openssl rand -hex 32); an invalid value prevents the server from starting.
• JWT_SECRET is generated on first boot and persisted in the volume. Set JWT_SECRET explicitly (32+ bytes, openssl rand -hex 32) if you manage secrets yourself.
• For production, set SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false on the Sub2API service so only HTTPS upstream URLs are accepted.
• RUN_MODE=simple disables the SaaS/billing features for private use; in production it additionally requires SIMPLE_MODE_CONFIRM=true.

Important notice

Using this project may violate the terms of service of Anthropic and other upstream providers. Use it in compliance with the laws of your country or region; account bans, service interruptions and data loss are the user's own risk. The upstream project does not grant any commercial authorization.

Upstream project: https://github.com/Wei-Shaw/sub2api