Long post warning, recommend saving it first.

Solution Overview: sub2api + Multi-Account Pool Architecture#

• Unified Interface: Consolidates multiple Claude/Codex Plus accounts into a single API endpoint.
• Intelligent Scheduling: Automatically selects available accounts based on real-time quota to avoid rate limits.
• Load Balancing: Supports account grouping and weight configuration for reasonable request distribution.
• Carpool Sharing: Can generate multiple API Keys to share usage with friends.
• Usage Monitoring: Web panel for real-time viewing of each account's usage and request statistics.

Your Application/Tool
    ↓ (Uses API Key)
sub2api Gateway (Docker Deployment)
    ↓ (Intelligent Scheduling)
Account Pool: Plus Account 1, Plus Account 2, Plus Account 3...
    ↓
Claude/Codex Official API

Costs and Prerequisites#

1. An overseas VPS
   • Recommended: Singapore node for low latency and stable access from China.
   • A lightweight server from Alibaba Cloud/Tencent Cloud for about 30 yuan/month is sufficient.
2. Several Codex Plus accounts
   • The quantity depends on your usage intensity. It's recommended to start with 2 for testing and add more if needed.
   • ⚠️ Important Note: This is not about purchasing the accounts themselves, but paying for the service of being "invited into a Business team." You need to provide an email address already registered with OpenAI. The seller will invite your account into their Business team, granting you access to Codex 5.3.
   • Price on Xianyu is usually around 10 yuan/account (monthly billing).
3. A domain name (Recommended)
   • ⚠️ Important: Direct access via IP may cause frontend JS files to fail to load. It is strongly recommended to bind a domain name.
   • You can purchase a domain name on platforms like Alibaba Cloud or Tencent Cloud. A cheap one will do.

Deployment Steps#

Prerequisites#

1. Install Docker and Docker Compose
   Ensure Docker and Docker Compose V2 are installed on your server.
2. Install 1Panel (Recommended)
   1Panel is an open-source Linux server operation and maintenance management panel. It facilitates managing Docker containers, configuring reverse proxies, binding domain names, etc. It is highly recommended, especially for scenarios requiring domain name access.
   Installation command:

   bash -c "$(curl -sSL https://resource.fit2cloud.com/1panel/package/v2/quick_start.sh)"

   Installation steps:
   1. Select language (Chinese/English).
   2. Press Enter all the way to use default configurations.
   3. Important: Remember the following displayed after installation:
      • Security entry
      • Panel username
      • Panel password
      • External access address (e.g., http://YOUR_SERVER_IP:24045/security_entry)
   
   1. Access the external address in your browser and log in with the username and password.
   
   If you cannot access the panel:
   It is likely that the server firewall has not opened the port. 1Panel uses port 24045 by default. You need to add an inbound rule in your cloud server's security group to open this port.
   
   The role of 1Panel:
   • Visually manage Docker containers.
   • Configure Nginx reverse proxy and bind domain names.
   • Automatically apply for and renew SSL certificates (Let's Encrypt).
   • Monitor server resource usage.
   After installation, you can proceed with deploying sub2api.

Deploying sub2api#

• docker-compose.local.yml: Data is stored in a local directory, making backup and migration easier (Recommended).
• docker-compose.yml: Data is stored in Docker named volumes, suitable for simple scenarios.

Docker Compose Deployment Steps#

mkdir -p ~/sub2api && cd ~/sub2api

wget https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-compose.local.yml

curl -o docker-compose.local.yml https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-compose.local.yml

cat > .env << 'EOF'

# Database Configuration
POSTGRES_USER=sub2api
POSTGRES_PASSWORD=your_secure_db_password_here
POSTGRES_DB=sub2api

# Redis Configuration
REDIS_PASSWORD=your_secure_redis_password_here

# Application Configuration
JWT_SECRET=your_jwt_secret_here_min_32_chars
ADMIN_PASSWORD=your_admin_password_here

# Service Port (Optional, default 8080)
APP_PORT=8080
EOF

# Generate JWT_SECRET (at least 32 characters)
openssl rand -base64 32

Generate ADMIN_PASSWORD#

openssl rand -base64 16

sed -i "s|your_jwt_secret_here_min_32_chars|$(openssl rand -hex 32)|" .env
sed -i "s|your_admin_password_here|$(openssl rand -hex 16)|" .env
sed -i "s|your_secure_db_password_here|$(openssl rand -hex 16)|" .env
sed -i "s|your_secure_redis_password_here|$(openssl rand -hex 16)|" .env

docker compose -f docker-compose.local.yml up -d

docker compose -f docker-compose.local.yml ps

• sub2api (main service)
• postgres (database)
• redis (cache)

cat .env | grep ADMIN_PASSWORD

cat .env

Configure Domain Access (Recommended)#

1. In 1Panel, go to "Websites""Create Website" → select "Reverse Proxy"
2. Fill in the configuration:
   • Main Domain: Enter your domain (e.g., sub2api.yourdomain.com)
   • Proxy Address: 127.0.0.1:8080
   • Keep other options as default
3. Click confirm to create

• Record Type: A
• Host Record: sub2api (or your desired subdomain)
• Record Value: Your server's public IP
• TTL: Default value (usually 600 seconds)

First Login#

• Email: admin@sub2api.local
• Password: The ADMIN_PASSWORD set in the .env file

cat ~/sub2api/.env | grep ADMIN_PASSWORD

Configure Account Pool#

1. Create Account Groups#

• Group Name: A name for the group (e.g., "Codex Account Pool")
• Platform: Select the platform type
  • For Codex Plus accounts, select OpenAI
  • For official Claude accounts, select Claude
  • For Antigravity service, select Antigravity
• Description: Group description (optional)

2. Add Codex Plus Accounts#

• Account Type: Select based on account type
  • Codex Plus accounts: Select OpenAI
  • Official Claude accounts: Select Claude
  • Antigravity service: Select Antigravity
• Session Key: Enter the account's Session Token
• Account Name: Give the account a recognizable name (e.g., "Codex Plus Account 1")
• Group: Select the group you just created (e.g., "Codex Account Pool")
• Weight: Higher number means higher scheduling probability (default 1 is fine)

1. Copy the authorization link and open it in a new tab
2. Log in to the platform, which will redirect to the authorization page
3. Click authorize, which will redirect to a localhost address
4. Copy the complete localhost link and paste it back

3. Create API Key#

• Key Name: Name for the API Key (e.g., "My Development Environment")
• Rate Limit: Rate limiting (optional)
• Quota: Quota limit (optional)
• Account Groups: Select the group(s) created earlier

4. Top Up Account (Using Redemption Codes)#

1. In the management panel, click "Redemption Codes"
2. Fill in the redemption code information:
   • Amount: Top-up amount (virtual quota for internal billing)
   • Expiry Date: Redemption code validity (optional)
   • Max Uses: Maximum number of uses (default 1)
3. Click create, and the system will generate a redemption code

1. In the management panel, click the user menu in the top right corner"Redeem"
2. Enter the generated redemption code
3. Click "Redeem" to confirm the top-up
4. After successful top-up, your account balance will increase, and the API Key can be used normally

• The redemption code system is mainly for carpooling scenarios. The admin can generate codes and distribute them to other users.
• For personal use, generate a large-amount code and top up your account in one go.
• The top-up amount is virtual and does not involve real currency transactions. It is used for internal quota management.

Using API in Coding Agents#

Method 1: Quick Configuration with cc-switch (Recommended)#

• API Keys are bound to account groups. Different platforms require creating corresponding API Keys.
• For example: Codex, Claude, and Gemini require three separate API Keys (each associated with the corresponding account group).
• For unified management, you can customize the name when creating API Keys and use the same Key value (but ensure the Key is associated with account groups for all platforms).

1. Claude Configuration

1. Codex Configuration

Method 2: Manual Configuration File Modification#

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://sub2api.yourdomain.com/v1",
        "apiKey": "your_claude_api_key"
      }
    },
    "google": {
      "options": {
        "baseURL": "https://sub2api.yourdomain.com/v1beta",
        "apiKey": "your_gemini_api_key"
      }
    },
    "openai": {
      "name": "OpenAI",
      "options": {
        "baseURL": "https://sub2api.yourdomain.com/v1",
        "apiKey": "your_codex_api_key"
      }
    }
  }
}

• Replace sub2api.yourdomain.com with your actual domain
• Replace your_api_key with the API Key created in the sub2api management panel
• Use the corresponding API endpoints for different platforms (Claude and OpenAI use /v1, Google uses /v1beta)

Usage Effects and Considerations#

1. Seamless Switching: When an account hits a rate limit, the system automatically switches to another available account, keeping your workflow uninterrupted.
2. Usage Monitoring: View real-time usage and remaining quotas for each account in the management panel.
3. Cost Optimization: When sharing among multiple users, the cost per person is significantly reduced.

• Single Heavy User: 3-5 Plus accounts are generally sufficient.
• 2-3 Users Carpooling: 2 accounts per person, totaling 4-6 accounts in the pool.
• Small Team (5 people): 10-15 accounts, averaging 2-3 per person.

Common Issues#

1. Frontend JS Files Fail to Load via IP#

1. Prepare a domain and point an A record to your server IP.
2. Configure a reverse proxy using 1Panel:
   • In 1Panel, go to "Websites""Create Website" → "Reverse Proxy"
   • Domain: Enter your domain (e.g., sub2api.yourdomain.com)
   • Proxy Address: http://127.0.0.1:8080
   • Enable HTTPS (optional)
3. Access via domain: https://sub2api.yourdomain.com

environment:
  - BASE_URL=http://YOUR_SERVER_IP:8080

docker compose -f docker-compose.local.yml down
docker compose -f docker-compose.local.yml up -d

Summary#

• Personal Heavy Use: Say goodbye to single-account rate limits. Multi-account auto-rotation keeps your AI coding workflow continuous.
• Carpooling with Friends: Share costs among several people. Each person pays very little for ample usage. The redemption code system allows flexible quota allocation.
• Team Collaboration: For small development teams, this solution maximizes the value of subscription accounts. Compared to each person buying a Plus account individually, a centrally managed account pool is not only cheaper but also allows dynamic resource allocation based on actual usage, preventing idle accounts while others frequently hit rate limits. Team admins can monitor usage and set quota limits to ensure fair resource distribution.

• sub2api GitHub: https://github.com/Wei-Shaw/sub2api
• Online Demo: https://demo.sub2api.org/
• 1Panel Website: https://1panel.cn/

Thread#

Recent new articles. If they help you, please give them a like — it really matters to me, thank you! 🫡#

Author: mkdev | I love eating Qing Bu Liang (@mkdir700) URL: https://x.com/mkdir700/status/2030299845739811086

https://t.co/KODdmd8r7M