Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/wei-shaw/sub2api

Sub2API-CRS2 一站式开源中转服务，让 Claude、Openai 、Gemini、Antigravity订阅统一接入，支持拼车共享，更高效分摊成本，原生工具无缝使用。
https://github.com/wei-shaw/sub2api

2api antigravity2api cc2api claude claude-code codex crs crs2 gemini

Last synced: about 2 hours ago
JSON representation

Sub2API-CRS2 一站式开源中转服务，让 Claude、Openai 、Gemini、Antigravity订阅统一接入，支持拼车共享，更高效分摊成本，原生工具无缝使用。

Awesome Lists containing this project

README 

          
# Sub2API






[![Go](https://img.shields.io/badge/Go-1.25.5-00ADD8.svg)](https://golang.org/)

[![Vue](https://img.shields.io/badge/Vue-3.4+-4FC08D.svg)](https://vuejs.org/)

[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15+-336791.svg)](https://www.postgresql.org/)

[![Redis](https://img.shields.io/badge/Redis-7+-DC382D.svg)](https://redis.io/)

[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED.svg)](https://www.docker.com/)



**AI API Gateway Platform for Subscription Quota Distribution**



English | [中文](README_CN.md)






---



## Demo



Try Sub2API online: **https://v2.pincc.ai/**



Demo credentials (shared demo environment; **not** created automatically for self-hosted installs):



| Email | Password |

|-------|----------|

| admin@sub2api.com | admin123 |



## Overview



Sub2API is an AI API gateway platform designed to distribute and manage API quotas from AI product subscriptions (like Claude Code $200/month). Users can access upstream AI services through platform-generated API Keys, while the platform handles authentication, billing, load balancing, and request forwarding.



## Features



- **Multi-Account Management** - Support multiple upstream account types (OAuth, API Key)

- **API Key Distribution** - Generate and manage API Keys for users

- **Precise Billing** - Token-level usage tracking and cost calculation

- **Smart Scheduling** - Intelligent account selection with sticky sessions

- **Concurrency Control** - Per-user and per-account concurrency limits

- **Rate Limiting** - Configurable request and token rate limits

- **Admin Dashboard** - Web interface for monitoring and management



## Tech Stack



| Component | Technology |

|-----------|------------|

| Backend | Go 1.25.5, Gin, Ent |

| Frontend | Vue 3.4+, Vite 5+, TailwindCSS |

| Database | PostgreSQL 15+ |

| Cache/Queue | Redis 7+ |



---



## Documentation



- Dependency Security: `docs/dependency-security.md`



---



## Deployment



### Method 1: Script Installation (Recommended)



One-click installation script that downloads pre-built binaries from GitHub Releases.



#### Prerequisites



- Linux server (amd64 or arm64)

- PostgreSQL 15+ (installed and running)

- Redis 7+ (installed and running)

- Root privileges



#### Installation Steps



```bash

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

```



The script will:

1. Detect your system architecture

2. Download the latest release

3. Install binary to `/opt/sub2api`

4. Create systemd service

5. Configure system user and permissions



#### Post-Installation



```bash

# 1. Start the service

sudo systemctl start sub2api



# 2. Enable auto-start on boot

sudo systemctl enable sub2api



# 3. Open Setup Wizard in browser

# http://YOUR_SERVER_IP:8080

```



The Setup Wizard will guide you through:

- Database configuration

- Redis configuration

- Admin account creation



#### Upgrade



You can upgrade directly from the **Admin Dashboard** by clicking the **Check for Updates** button in the top-left corner.



The web interface will:

- Check for new versions automatically

- Download and apply updates with one click

- Support rollback if needed



#### Useful Commands



```bash

# Check status

sudo systemctl status sub2api



# View logs

sudo journalctl -u sub2api -f



# Restart service

sudo systemctl restart sub2api



# Uninstall

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash -s -- uninstall -y

```



---



### Method 2: Docker Compose



Deploy with Docker Compose, including PostgreSQL and Redis containers.



#### Prerequisites



- Docker 20.10+

- Docker Compose v2+



#### Installation Steps



```bash

# 1. Clone the repository

git clone https://github.com/Wei-Shaw/sub2api.git

cd sub2api



# 2. Enter the deploy directory

cd deploy



# 3. Copy environment configuration

cp .env.example .env



# 4. Edit configuration (set your passwords)

nano .env

```



**Required configuration in `.env`:**



```bash

# PostgreSQL password (REQUIRED - change this!)

POSTGRES_PASSWORD=your_secure_password_here



# Optional: Admin account

ADMIN_EMAIL=admin@example.com

ADMIN_PASSWORD=your_admin_password



# Optional: Custom port

SERVER_PORT=8080



# Optional: Security configuration

# Enable URL allowlist validation (false to skip allowlist checks, only basic format validation)

SECURITY_URL_ALLOWLIST_ENABLED=false



# Allow insecure HTTP URLs when allowlist is disabled (default: false, requires https)

# ⚠️ WARNING: Enabling this allows HTTP (plaintext) URLs which can expose API keys

#             Only recommended for:

#             - Development/testing environments

#             - Internal networks with trusted endpoints

#             - When using local test servers (http://localhost)

# PRODUCTION: Keep this false or use HTTPS URLs only

SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=false



# Allow private IP addresses for upstream/pricing/CRS (for internal deployments)

SECURITY_URL_ALLOWLIST_ALLOW_PRIVATE_HOSTS=false

```



```bash

# 5. Start all services

docker-compose up -d



# 6. Check status

docker-compose ps



# 7. View logs

docker-compose logs -f sub2api

```



#### Access



Open `http://YOUR_SERVER_IP:8080` in your browser.



#### Upgrade



```bash

# Pull latest image and recreate container

docker-compose pull

docker-compose up -d

```



#### Useful Commands



```bash

# Stop all services

docker-compose down



# Restart

docker-compose restart



# View all logs

docker-compose logs -f

```



---



### Method 3: Build from Source



Build and run from source code for development or customization.



#### Prerequisites



- Go 1.21+

- Node.js 18+

- PostgreSQL 15+

- Redis 7+



#### Build Steps



```bash

# 1. Clone the repository

git clone https://github.com/Wei-Shaw/sub2api.git

cd sub2api



# 2. Install pnpm (if not already installed)

npm install -g pnpm



# 3. Build frontend

cd frontend

pnpm install

pnpm run build

# Output will be in ../backend/internal/web/dist/



# 4. Build backend with embedded frontend

cd ../backend

go build -tags embed -o sub2api ./cmd/server



# 5. Create configuration file

cp ../deploy/config.example.yaml ./config.yaml



# 6. Edit configuration

nano config.yaml

```



> **Note:** The `-tags embed` flag embeds the frontend into the binary. Without this flag, the binary will not serve the frontend UI.



**Key configuration in `config.yaml`:**



```yaml

server:

  host: "0.0.0.0"

  port: 8080

  mode: "release"



database:

  host: "localhost"

  port: 5432

  user: "postgres"

  password: "your_password"

  dbname: "sub2api"



redis:

  host: "localhost"

  port: 6379

  password: ""



jwt:

  secret: "change-this-to-a-secure-random-string"

  expire_hour: 24



default:

  user_concurrency: 5

  user_balance: 0

  api_key_prefix: "sk-"

  rate_multiplier: 1.0

```



Additional security-related options are available in `config.yaml`:



- `cors.allowed_origins` for CORS allowlist

- `security.url_allowlist` for upstream/pricing/CRS host allowlists

- `security.url_allowlist.enabled` to disable URL validation (use with caution)

- `security.url_allowlist.allow_insecure_http` to allow HTTP URLs when validation is disabled

- `security.url_allowlist.allow_private_hosts` to allow private/local IP addresses

- `security.response_headers.enabled` to enable configurable response header filtering (disabled uses default allowlist)

- `security.csp` to control Content-Security-Policy headers

- `billing.circuit_breaker` to fail closed on billing errors

- `server.trusted_proxies` to enable X-Forwarded-For parsing

- `turnstile.required` to require Turnstile in release mode



**⚠️ Security Warning: HTTP URL Configuration**



When `security.url_allowlist.enabled=false`, the system performs minimal URL validation by default, **rejecting HTTP URLs** and only allowing HTTPS. To allow HTTP URLs (e.g., for development or internal testing), you must explicitly set:



```yaml

security:

  url_allowlist:

    enabled: false                # Disable allowlist checks

    allow_insecure_http: true     # Allow HTTP URLs (⚠️ INSECURE)

```



**Or via environment variable:**



```bash

SECURITY_URL_ALLOWLIST_ENABLED=false

SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true

```



**Risks of allowing HTTP:**

- API keys and data transmitted in **plaintext** (vulnerable to interception)

- Susceptible to **man-in-the-middle (MITM) attacks**

- **NOT suitable for production** environments



**When to use HTTP:**

- ✅ Development/testing with local servers (http://localhost)

- ✅ Internal networks with trusted endpoints

- ✅ Testing account connectivity before obtaining HTTPS

- ❌ Production environments (use HTTPS only)



**Example error without this setting:**

```

Invalid base URL: invalid url scheme: http

```



If you disable URL validation or response header filtering, harden your network layer:

- Enforce an egress allowlist for upstream domains/IPs

- Block private/loopback/link-local ranges

- Enforce TLS-only outbound traffic

- Strip sensitive upstream response headers at the proxy



```bash

# 6. Run the application

./sub2api

```



#### Development Mode



```bash

# Backend (with hot reload)

cd backend

go run ./cmd/server



# Frontend (with hot reload)

cd frontend

pnpm run dev

```



#### Code Generation



When editing `backend/ent/schema`, regenerate Ent + Wire:



```bash

cd backend

go generate ./ent

go generate ./cmd/server

```



---



## Simple Mode



Simple Mode is designed for individual developers or internal teams who want quick access without full SaaS features.



- Enable: Set environment variable `RUN_MODE=simple`

- Difference: Hides SaaS-related features and skips billing process

- Security note: In production, you must also set `SIMPLE_MODE_CONFIRM=true` to allow startup



---



## Antigravity Support



Sub2API supports [Antigravity](https://antigravity.so/) accounts. After authorization, dedicated endpoints are available for Claude and Gemini models.



### Dedicated Endpoints



| Endpoint | Model |

|----------|-------|

| `/antigravity/v1/messages` | Claude models |

| `/antigravity/v1beta/` | Gemini models |



### Claude Code Configuration



```bash

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"

export ANTHROPIC_AUTH_TOKEN="sk-xxx"

```



### Hybrid Scheduling Mode



Antigravity accounts support optional **hybrid scheduling**. When enabled, the general endpoints `/v1/messages` and `/v1beta/` will also route requests to Antigravity accounts.



> **⚠️ Warning**: Anthropic Claude and Antigravity Claude **cannot be mixed within the same conversation context**. Use groups to isolate them properly.



### Known Issues



In Claude Code, Plan Mode cannot exit automatically. (Normally when using the native Claude API, after planning is complete, Claude Code will pop up options for users to approve or reject the plan.)



**Workaround**: Press `Shift + Tab` to manually exit Plan Mode, then type your response to approve or reject the plan.



---



## Project Structure



```

sub2api/

├── backend/                  # Go backend service

│   ├── cmd/server/           # Application entry

│   ├── internal/             # Internal modules

│   │   ├── config/           # Configuration

│   │   ├── model/            # Data models

│   │   ├── service/          # Business logic

│   │   ├── handler/          # HTTP handlers

│   │   └── gateway/          # API gateway core

│   └── resources/            # Static resources

│

├── frontend/                 # Vue 3 frontend

│   └── src/

│       ├── api/              # API calls

│       ├── stores/           # State management

│       ├── views/            # Page components

│       └── components/       # Reusable components

│

└── deploy/                   # Deployment files

    ├── docker-compose.yml    # Docker Compose configuration

    ├── .env.example          # Environment variables for Docker Compose

    ├── config.example.yaml   # Full config file for binary deployment

    └── install.sh            # One-click installation script

```



## License



MIT License



---






**If you find this project useful, please give it a star!**