Sub2API: Self-Hosted Gateway for AI Subscriptions
/sub2api
Sub2API turns a stack of Claude, OpenAI, Gemini, or Grok subscription accounts into one API endpoint you can meter, rate-limit, and resell to other users. It's built for that operational reality, with sticky sessions, composite provider routing, and payment collection wired in rather than bolted on. The catch: the README itself warns that using it may violate upstream providers' terms of service.
What is Sub2API
Sub2API is a self-hosted Go gateway that sits between end users and upstream AI provider accounts, converting subscription-based access to Claude, OpenAI, Gemini, and Grok into distributable API keys. Admins connect upstream accounts via OAuth or API key, and Sub2API forwards requests, tracks token usage per user, and enforces concurrency and rate limits before billing through its built-in payment system.
Core features
- ✓Multi-account management: connects upstream accounts via OAuth or a raw API key, so one deployment can pool several Claude, OpenAI, Gemini, or Grok accounts behind one gateway.
- ✓API key distribution: generates a separate API key per user from the admin dashboard, so nobody but the operator ever sees the real upstream credential.
- ✓Token-level billing: tracks usage per request and calculates cost at the token level instead of a flat per-call fee.
- ✓Smart scheduling with sticky sessions: picks which upstream account handles a request and keeps a session pinned to that account, which matters for tools like Claude Code that expect conversational state to stay on one backend.
- ✓Concurrency and rate limiting: caps how many simultaneous requests and how much throughput a given user or account can use.
- ✓Built-in payment system: EasyPay, Alipay, WeChat Pay, and Stripe are wired in directly so users can top up their own balance without a separate billing service.
- ✓Composite groups: an admin routing layer that resolves a requested model name to a concrete upstream provider across multiple accounts, so one logical model can fan out to several backends.
- ✓Admin dashboard with iframe embedding: lets you drop an external system, such as a ticketing tool, straight into the dashboard.
Common use cases
- •A small team or friend group pooling several paid Claude, ChatGPT, or Gemini subscriptions ("拼车") into one shared, metered endpoint instead of everyone buying their own plan.
- •Fronting Claude Code or Codex with a self-hosted relay so only your own key-rotation logic touches upstream credentials, keeping them off client machines.
- •Running a small paid relay: the built-in Stripe, Alipay, and WeChat Pay billing plus per-user API keys are aimed at operators reselling subscription quota.
- •Load-balancing multiple upstream accounts of the same provider so one high-traffic app doesn't get rate-limited on a single account.
Installing Sub2API
Installing Sub2API is documented for Linux servers via a one-line script: `curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash`. It requires a Linux server (amd64 or arm64), PostgreSQL 15+ and Redis 7+ already installed and running, and root privileges. The script detects your architecture, downloads the latest binary release, installs it to /opt/sub2api, and sets up a systemd service with its own system user. After that you start and enable the service with systemctl, then open the Setup Wizard at http://YOUR_SERVER_IP:8080 to configure the database, Redis, and the first admin account.
Running Sub2API for the first time
Once the Setup Wizard has created your admin account, connect upstream AI accounts (Claude, OpenAI, Gemini, or Grok, via OAuth or a raw API key) from the admin dashboard, then generate Sub2API keys for the people or apps that should relay through them. Point Claude Code, Codex, or any OpenAI/Anthropic-compatible client at your Sub2API endpoint with one of those generated keys instead of the provider's own key. Running Codex through Nginx? Add `underscores_in_headers on;` to the Nginx http block first: Nginx strips headers like `session_id` by default, which breaks the sticky-session routing multi-account setups depend on. Upgrades run from inside the dashboard, where a "Check for Updates" button downloads and applies new releases with one click and supports rollback.
Strengths
- ✓Payment collection (Alipay, WeChat Pay, Stripe, EasyPay) is built into the gateway itself, so operators don't have to wire up a separate billing service just to let users top up.
- ✓Composite groups let one logical model route across several upstream provider accounts instead of hardcoding a single backend.
- ✓Sticky sessions are handled natively, which is the specific thing that breaks first when people try to load-balance Claude Code or Codex traffic by hand.
- ✓Multi-account support for both OAuth and raw API keys covers how subscription products and pay-as-you-go APIs each authenticate.
Limitations and risks
- △The README opens with a direct warning that using Sub2API could run afoul of the service terms set by Anthropic or other upstream providers, a legal and account-suspension risk the project places on the operator, not something the software mitigates.
- △Deployment is Linux-server-only in the documented method, and you're expected to already have PostgreSQL 15+ and Redis 7+ running before you touch the installer; there's no bundled database.
- △The README's own body is dominated by a long list of paid third-party relay-service ads ahead of the actual documentation, which makes it harder to find the parts you need on a first read.
- △LGPL-3.0 licensing means any modified version you distribute, not just link to, carries copyleft obligations, a different bar than a permissive MIT/Apache project.
Similar projects
Who should use Sub2API
Sub2API fits a small team or friend group that already pays for multiple Claude, OpenAI, Gemini, or Grok subscriptions and wants to pool that quota behind one gateway instead of everyone juggling separate keys and bills. It also fits someone willing to run a small paid relay: the built-in Stripe/Alipay/WeChat Pay/EasyPay billing and per-user API keys are clearly aimed at operators reselling subscription capacity, not just personal use. It's not a fit if you won't accept the terms-of-service risk the README calls out up front, or if you don't want to run and maintain your own PostgreSQL and Redis on a Linux box.
Frequently asked questions
Sub2API is open source under the LGPL-3.0 license, so self-hosting the code itself costs nothing beyond your own server, PostgreSQL, and Redis. The README's own warning that using it against upstream providers' terms of service carries legal and account risk is a separate issue from the software's price.
Sub2API supports Claude Code and Codex as upstream integration targets. The README documents a specific Nginx setting, `underscores_in_headers on;`, needed when proxying Codex CLI traffic through Sub2API, because sticky-session headers get dropped otherwise.
Sub2API bills usage at the token level per request and ties it to a built-in payment system supporting EasyPay, Alipay, WeChat Pay, and Stripe, so users can top up their own balance without the operator standing up a separate payment integration.
Sub2API requires PostgreSQL 15+ as its primary database and Redis 7+ for cache and queue duties; both need to be installed and running before the installer script will set up the service.
Sub2API can be upgraded from inside its own Admin Dashboard: a "Check for Updates" button checks for new releases, downloads and applies them with one click, and supports rolling back if the update causes problems.
Sub2API works behind Nginx, but the README flags one setting to add: `underscores_in_headers on;` in the Nginx http block, since Nginx drops headers containing underscores, like session_id, by default, breaking sticky-session routing in multi-account setups.
The problem it solves
People who pay for a Claude, ChatGPT, or Gemini subscription get a chat client, not an API key, but tools like Claude Code or Codex still expect something that looks like an API endpoint. Sub2API's own README frames the gap directly: it exists to let a group split the cost of those subscriptions ("拼车", quota-carpooling) by exposing one or more upstream accounts as distributable, individually-metered API keys, instead of everyone buying a separate seat.
Related repositories
Is sub2api worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of sub2api.