Sub2API deployment guide: build an AI API proxy server

Short version

If you want to run your own usable API proxy, an open-source project such as Sub2API is often enough. The core flow is simple: prepare a Linux server, deploy the service, initialize the database and admin account, then give users the external Base URL and API Key.

Best-fit use cases

Sub2API is a better fit for people who want to:

• Manage multiple upstream accounts in one place
• Issue a unified API key to team members
• Control top-ups, permissions, and forwarding rules themselves
• Run a usable private proxy before committing to a more complex platform

If you only want to test an interface temporarily, you can use a demo environment to understand the flow. For real use, self-deployment is still the better choice.

Before deployment

Prepare three things first:

1. A Linux cloud server, preferably AMD64 or ARM64
2. PostgreSQL and Redis, or a Docker Compose setup that includes both
3. A domain that resolves to the server, so you can add certificates and access the admin panel cleanly

If you plan to reverse proxy through Nginx, enable underscores_in_headers on; in the http block. Otherwise, some multi-account scenarios can fail because headers are dropped.

Recommended deployment methods

The Sub2API documentation commonly points to two deployment paths:

• One-click install script: good for getting online quickly. The script downloads the binary, creates the service, and initializes the directory structure.
• Docker Compose: good when you want clearer control over data directories, migration, and backups.

For a first deployment, Docker is usually easier to reason about. If you prefer production-style systemd management, the install script is also convenient.

Option 1: Docker deployment

The rough flow is:

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose up -d

The script usually prepares:

• docker-compose.local.yml
• .env
• Security keys
• Local data directories

That also makes future server migration easier, because the whole setup can be packaged together.

To inspect runtime logs:

docker compose logs -f sub2api

Option 2: install script

If you prefer a direct systemd service, use the official one-click install script. It installs the program on the server, creates a service, and starts the initialization wizard.

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

After installation, the initialization page is usually available at http://server-ip:8080. Continue by configuring the database, Redis, and admin account.

What to check during initialization

In the setup panel, confirm:

• The database connection works
• Redis is healthy
• The admin account has been created
• The port is open to the outside
• The domain and reverse proxy are already connected

If other people will use the service, define the boundary between admin users and normal users during initialization. It is much more annoying to redesign this later.

Give access to users

Once the panel is running, users usually need two values:

• Base URL
• API Key

Users can enter those values in Claude Code, Codex, Cursor, or any compatible tool. Requests go to your proxy first, then the proxy forwards them to the upstream service.

What this kind of proxy really is

Think of it as a middle layer.

Users send requests to your proxy. The proxy then forwards those requests according to the upstream accounts, models, and rules you configured. This lets you manage accounts, permissions, billing, and distribution in one place.

Common pitfalls

• Nginx drops headers: if you use a reverse proxy, preserve underscore headers.
• Database or Redis is down: the initialization panel opening does not mean all backend dependencies are healthy.
• Domain is incomplete: being able to access the panel does not guarantee the external API address works.
• Account authorization fails: check browser sessions, proxy settings, callback URLs, and upstream account status first.

Closing advice

If this is your first proxy deployment, do not start with an overly complex architecture. Run the smallest usable version first. Confirm the panel, account, forwarding, and API calls all work, then add domains, certificates, reverse proxy rules, and more upstream accounts step by step.