SubioHub is a self-hosted AI gateway platform built for unified upstream access, API key and OAuth account integration, model relay, usage metering, and operational management. It helps teams expose a consistent OpenAI-compatible interface while handling provider onboarding, key-based model forwarding, account pools, routing policies, billing rules, and admin workflows in one place.

• Multi-Upstream Access - Support multiple upstream account types and provider credentials, including OAuth and API Key
• OpenAI-Compatible Model Relay - Expose unified relay endpoints for model forwarding, key passthrough, and provider abstraction
• API Key Distribution - Generate and manage user-facing API Keys, quotas, and access scopes
• Model Routing and Scheduling - Route requests by model, channel, policy, and sticky session strategies
• Precise Billing - Token-level usage tracking, pricing rules, and cost calculation
• Concurrency Control - Per-user and per-account concurrency limits
• Rate Limiting - Configurable request and token rate limits
• Built-in Payment System - Supports EasyPay, Alipay, WeChat Pay, and Stripe for user self-service top-up, no separate payment service needed (Configuration Guide)
• Admin Dashboard - Web interface for channels, accounts, models, usage, payments, and operational management
• External System Integration - Embed external systems (e.g. ticketing) via iframe to extend the admin dashboard

• Team Gateway - Unify multiple AI providers behind one internal API endpoint
• API Key to Model Relay - Use your own upstream keys/accounts to relay Claude, Gemini, OpenAI-compatible, and other model traffic through one platform
• Subscription Resale - Allocate quota, keys, and routing policies to downstream users with billing controls
• Operations Console - Manage accounts, channels, proxies, limits, and monitoring from one dashboard
• Localized Content Delivery - Support multilingual announcements and news presentation on the public site

When using Nginx as a reverse proxy for SubioHub (or CRS) with Codex CLI, add the following to the http block in your Nginx configuration:

underscores_in_headers on;

Nginx drops headers containing underscores by default (e.g. session_id), which breaks sticky session routing in multi-account setups.

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

• Linux server (amd64 or arm64)
• PostgreSQL 15+ (installed and running)
• Redis 7+ (installed and running)
• Root privileges

curl -sSL https://raw.githubusercontent.com/dlxyz/SubioHub/main/deploy/install.sh | sudo bash

The script will:

1. Detect your system architecture
2. Download the latest release
3. Install binary to /opt/subiohub
4. Create systemd service
5. Configure system user and permissions

# 1. Start the service
sudo systemctl start subiohub

# 2. Enable auto-start on boot
sudo systemctl enable subiohub

# 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

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

# Check status
sudo systemctl status subiohub

# View logs
sudo journalctl -u subiohub -f

# Restart service
sudo systemctl restart subiohub

# Uninstall
curl -sSL https://raw.githubusercontent.com/dlxyz/SubioHub/main/deploy/install.sh | sudo bash -s -- uninstall -y

Deploy with Docker Compose, including PostgreSQL and Redis containers.

• Docker 20.10+
• Docker Compose v2+

Use the automated deployment script for easy setup:

# Create deployment directory
mkdir -p subiohub-deploy && cd subiohub-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/dlxyz/SubioHub/main/deploy/docker-deploy.sh | bash

# Start services
docker compose up -d

# View logs (copy the output to Notepad or another text editor to find the login password; username: `admin@subiohub.com`)
docker compose logs -f subiohub

What the script does:

• Downloads docker-compose.local.yml (saved as docker-compose.yml) and .env.example
• Generates secure credentials (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
• Creates .env file with auto-generated secrets
• Creates data directories (uses local directories for easy backup/migration)
• Displays generated credentials for your reference

If you prefer manual setup:

# 1. Clone the repository
git clone https://github.com/dlxyz/SubioHub.git
cd subiohub/deploy

# 2. Copy environment configuration
cp .env.example .env

# 3. Edit configuration (generate secure passwords)
nano .env

Required configuration in .env:

# PostgreSQL password (REQUIRED)
POSTGRES_PASSWORD=your_secure_password_here

# JWT Secret (RECOMMENDED - keeps users logged in after restart)
JWT_SECRET=your_jwt_secret_here

# TOTP Encryption Key (RECOMMENDED - preserves 2FA after restart)
TOTP_ENCRYPTION_KEY=your_totp_key_here

# Optional: Admin account
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# Optional: Custom port
SERVER_PORT=8080

Generate secure secrets:

# Generate JWT_SECRET
openssl rand -hex 32

# Generate TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# Generate POSTGRES_PASSWORD
openssl rand -hex 32

# 4. Create data directories (for local version)
mkdir -p data postgres_data redis_data

# 5. Start all services
# Option A: Local directory version (recommended - easy migration)
docker compose -f docker-compose.local.yml up -d

# Option B: Named volumes version (simple setup)
docker compose up -d

# 6. Check status
docker compose -f docker-compose.local.yml ps

# 7. View logs
docker compose -f docker-compose.local.yml logs -f subiohub

Recommendation: Use docker-compose.local.yml (deployed by script) for easier data management.

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

If admin password was auto-generated, find it in logs:

docker compose -f docker-compose.local.yml logs subiohub | grep "admin password"

# Pull latest image and recreate container
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

When using docker-compose.local.yml, migrate to a new server easily:

# On source server
docker compose -f docker-compose.local.yml down
cd ..
tar czf subiohub-complete.tar.gz subiohub-deploy/

# Transfer to new server
scp subiohub-complete.tar.gz user@new-server:/path/

# On new server
tar xzf subiohub-complete.tar.gz
cd subiohub-deploy/
docker compose -f docker-compose.local.yml up -d

# Stop all services
docker compose -f docker-compose.local.yml down

# Restart
docker compose -f docker-compose.local.yml restart

# View all logs
docker compose -f docker-compose.local.yml logs -f

# Remove all data (caution!)
docker compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

Build and run from source code for development or customization.

• Go 1.21+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

# 1. Clone the repository
git clone https://github.com/dlxyz/SubioHub.git
cd subiohub

# 2. Install next-web dependencies
cd next-web
npm install
npm run build

# 4. Build backend API service
cd ../backend
go build -o subiohub ./cmd/server

# 5. Create configuration file
cp ../deploy/config.example.yaml ./config.yaml

# 6. Edit backend configuration
nano config.yaml

# 7. Configure next-web environment
cd ../next-web
# Create .env.local manually and set:
# NEXT_SERVER_API_ORIGIN / NEXT_PUBLIC_API_URL / NEXT_PUBLIC_SITE_URL

Note: The production web architecture is backend + next-web.

Key configuration in config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "subiohub"

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

⚠️ Sora-related features are temporarily unavailable due to technical issues in upstream integration and media delivery. Please do not rely on Sora in production at this time. Existing gateway.sora_* configuration keys are reserved and may not take effect until these issues are resolved.

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:

security:
  url_allowlist:
    enabled: false                # Disable allowlist checks
    allow_insecure_http: true     # Allow HTTP URLs (⚠️ INSECURE)

Or via environment variable:

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

# 7. Run the backend
./subiohub

# Backend (with hot reload)
cd backend
go run ./cmd/server

# next-web (with hot reload)
cd ../next-web
npm run dev

By default:

• Backend API runs on http://localhost:8080
• next-web runs on http://localhost:3000
• Recommended env vars for next-web: NEXT_SERVER_API_ORIGIN, NEXT_PUBLIC_API_URL, NEXT_PUBLIC_SITE_URL

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

cd backend
go generate ./ent
go generate ./cmd/server

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

SubioHub supports Antigravity accounts. After authorization, dedicated endpoints are available for Claude and Gemini models.

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

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.

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.

subiohub/
├── 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
│
├── next-web/                 # Primary Next.js web app
│   └── src/
│       ├── app/              # App Router pages
│       ├── components/       # UI components
│       ├── i18n/             # Route-based i18n
│       ├── lib/              # API clients and helpers
│       └── store/            # Client state stores
│
└── 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

Please read carefully before using this project:

🚨 Terms of Service Risk: Using this project may violate Anthropic's Terms of Service. Please read Anthropic's user agreement carefully before use. All risks arising from the use of this project are borne solely by the user.

📖 Disclaimer: This project is for technical learning and research purposes only. The author assumes no responsibility for account suspension, service interruption, or any other losses caused by the use of this project.

MIT License