Wei-Shaw/sub2api

Sub2API is a self-hosted gateway for teams that hold multiple AI product subscriptions and want to expose them as shared, metered API keys. Administrators register upstream accounts, group them, and issue Sub2API keys with per-user quotas; the platform handles authentication, token-level billing, load balancing, concurrency and rate limits, and request forwarding Overview.

How the gateway works

Upstream credentials can be OAuth subscription accounts or plain API keys Features. Requests arrive on protocol-compatible endpoints — OpenAI Chat Completions and Responses, Anthropic Messages, dedicated Antigravity paths, Grok Responses and media endpoints, and TypeSafe's native System One endpoint — and are forwarded to the matching upstream Grok / xAI Support. Smart scheduling selects accounts with sticky sessions, and composite groups resolve a requested model to a concrete provider across multiple upstreams Composite Groups. Admin tooling covers a web dashboard, built-in payments (EasyPay, Alipay, WeChat Pay, Stripe), and iframe embedding for external systems such as ticketing Payment guide.

Concrete workflow

An operator adds, say, a Grok OAuth account or xAI API-key account, creates a Grok group, attaches the account, then issues a user key bound to that group. Pointing the Grok CLI at the gateway's /v1 base URL with that key completes the setup; a user-page Use Key dialog generates the client config for macOS/Linux or Windows Grok / xAI Support. The same pattern applies to Claude Code and other clients through endpoint-specific base URLs. For individual developers or internal teams, RUN_MODE=simple hides SaaS features and skips billing; production startup then additionally requires SIMPLE_MODE_CONFIRM=true.

Requirements and deployment

The service needs PostgreSQL 15+ and Redis 7+ Tech stack. Four paths are documented:

• Install script (Linux amd64/arm64): downloads a prebuilt binary, installs to /opt/sub2api, sets up systemd; requires root, PostgreSQL and Redis. Updates are applied from the admin dashboard with rollback support.
• Docker Compose: requires Docker 20.10+ and Compose v2+. The local-directory variant keeps data in ordinary folders for easy backup and migration; the named-volume variant needs Docker commands to move data.
• Apple container: for Apple-silicon Macs on macOS 26 with container 1.1.0+, described as an operator-managed local workflow, not the recommended production path README.
• Build from source: Go 1.21+, Node.js 18+, PostgreSQL and Redis. A created config.yaml causes the setup wizard to be skipped, so the admin account is never created and login fails; the README's two recovery routes are to let the wizard write the config or temporarily move the file aside for first run.

Constraints worth knowing

The project's own notice warns that using it may violate upstream providers' terms of service, that account bans and data loss are borne by the user, and that the authors have not authorized commercial operation based on it Important Notice. Operationally, disabling the URL allowlist permits plaintext HTTP by default, so production deployments should keep HTTPS-only; the legacy forwarded-header path is enabled by default for upgrade compatibility and should be replaced with a finite trusted-proxy list README. Claude models from Anthropic and Antigravity must not share one conversation context, so groups must isolate them. Licensing is LGPL-3.0-or-later LICENSE.

HotRepo's take

The repository had 45,081 stars on 2026-10-29, when the daily board recorded +80 that day. The supplied board history is too sparse to support a trend judgement.