Sub2API Plus

AI API gateway for subscription quota distribution

English | 中文 | 日本語

Sub2API Plus is an independently maintained community fork of Sub2API. It is not an official upstream release and does not imply upstream affiliation, endorsement, support, or trademark permission.

• Using subscription accounts through a gateway may conflict with provider terms. Review the applicable agreements before deployment.
• Deployers are responsible for legal, privacy, security, and operational compliance.
• The project is provided without warranty under LGPL-3.0-or-later.

Sub2API Plus distributes and manages access to supported AI providers through platform-issued API keys. It provides authentication, billing, account scheduling, quota controls, auditing, and request forwarding.

• Multiple OAuth and API-key account types
• User API-key and group management
• Token-level usage and billing
• Account scheduling, failover, and session affinity
• Quotas, subscriptions, redemption codes, and payment integrations
• OpenAI-, Claude-, and Gemini-compatible gateway interfaces
• Operational monitoring, audit, and security controls
• Optional simple mode for individual or internal deployments

Simple mode uses RUN_MODE=simple. Production also requires SIMPLE_MODE_CONFIRM=true.

The installer supports fresh installation, version pinning or rollback, and uninstallation. Published binary tags use the immutable vX.Y.Z+custom.NNN format.

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | sudo bash

List published versions:

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | bash -s -- list-versions

Install or switch to an exact published version. The command below is directly usable; replace its immutable tag with another value returned by list-versions when needed:

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | sudo bash -s -- install --version 'v0.1.178+custom.001'

Roll back an existing binary installation to an earlier published version:

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | sudo bash -s -- rollback 'v0.1.177+custom.003'

Remove the service and binary while preserving /etc/sub2api:

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | sudo bash -s -- uninstall --yes

Also remove /etc/sub2api. Review backups first; this cannot be undone:

curl -sSL https://raw.githubusercontent.com/LuckyKuang/sub2api-plus/main/deploy/install.sh | sudo bash -s -- uninstall --yes --purge

Then open http://YOUR_SERVER_IP:8080 and complete the setup wizard.

When Nginx runs on the same host, bind Sub2API to 127.0.0.1 and configure only the Nginx peer under server.trusted_proxies. Nginx must overwrite, not append, client-IP headers. Preserve streaming and WebSocket traffic with HTTP/1.1 upgrade headers, disabled proxy buffering, long read/send timeouts, and no gzip for text/event-stream.

For Codex CLI or CRS-compatible clients, add this directive to the Nginx http block:

underscores_in_headers on;

Current Codex clients use the hyphenated session-id; legacy Codex/CRS-compatible clients may still send session_id. Nginx drops underscore headers by default, so keep this directive to preserve sticky session routing for those clients. Validate the complete configuration before reloading:

sudo nginx -t

After the configuration test succeeds, reload Nginx:

sudo systemctl reload nginx

Use the complete Nginx baseline and trusted-proxy guidance before exposing the service publicly.

The full example configuration is deploy/config.example.yaml.

Details:

• Grok / xAI
• Antigravity
• Sora status
• OpenAI Responses and WebSocket ingress
• Asynchronous image tasks

Custom releases use the following formats:

Git/GitHub: vX.Y.Z+custom.NNN
Application: X.Y.Z+custom.NNN
GHCR:        ghcr.io/luckykuang/sub2api-plus:vX.Y.Z-custom.NNN

Pin the immutable GHCR version tag for reproducible production deployments. latest is a moving convenience tag. See UPSTREAM.md for the upstream mapping and the release process for maintainer rules.

• Documentation index
• Deployment
• Development and contributions
• Release process
• Upstream mapping
• Security policy

Licensed under the GNU Lesser General Public License v3.0 or later. Original upstream copyright and license notices are retained.

Original upstream work: Copyright (c) 2026 Wesley Liddick

Sub2API Plus modifications: Copyright (c) 2026 LuckyKuang