GPT-Load 2.0: A Self-Hosted Gateway That Treats API Keys and Subscription Logins as One Problem

The Credential Mess GPT-Load Targets

Most AI gateway projects assume every upstream is an API key. GPT-Load starts from a different observation: a growing share of LLM access comes from subscription accounts, like Claude Pro, Codex, or Antigravity, where you log in via OAuth instead of pasting a key. Managing those accounts alongside traditional API keys means two different credential lifecycles, two failure modes, and no shared view of quota. GPT-Load 2.0 collapses that distinction. The README states that Codex, Claude, Antigravity, Grok, and API-key channels share credential management, scheduling, and health handling. That is the core problem it solves: one mechanism for both credential types, so a team does not need separate tooling for each upstream. The intended user is a developer or small platform team that self-hosts a gateway because they want control over routing and cost, not a managed service.

Architecture: Groups, Channels, and AccessKeys

The data model visible in the README has three layers. A channel represents an upstream service and holds one or more credentials, which can be API keys or completed OAuth flows for subscription accounts. A group picks a channel, then defines which models are available and the runtime policy for that set. An AccessKey is what your application actually sends to the gateway; it binds to groups and client protocols. This separation means you can rotate credentials inside a channel without touching the AccessKey your app uses. The gateway exposes native protocols, so clients keep their OpenAI, Anthropic, or Gemini interfaces, and GPT-Load translates to the upstream. The management UI is embedded and backed by SQLite, MySQL, or PostgreSQL, with local credential encryption. The architecture is straightforward: a single entry point, a routing layer that applies weights and health checks, and a storage backend for logs and usage.

Scheduling, Failover, and Session Affinity

The README lists concrete mechanisms for keeping requests alive when a credential fails. Multi-credential scheduling with configurable weights lets you send more traffic to accounts you trust. Retries, cooldown, and blacklisting reduce the blast radius when one account gets rate-limited or returns errors. Session affinity is also mentioned, which matters for subscription channels that may have stateful sessions after OAuth. The documentation does not give exact algorithms or default timeouts, so you cannot know from the README how aggressive the retry logic is or whether blacklisting is permanent. That is a gap. A production user would need to read the source or test empirically. The presence of these features is real, but the tuning knobs are not documented in the material provided, which is a limitation for anyone planning a rollout.

Getting It Running: Commands and Configuration

The quick start is Docker Compose based. You clone the repository, copy .env.example to .env, then run docker compose up -d. The health check is curl --fail http://127.0.0.1:3001/health. A management key is generated on first start and stored at /app/data/auth.key inside the container; you read it with docker compose exec. You can also set AUTH_KEY explicitly in .env. The service listens on loopback by default, which is a sensible security default. Initial setup has three steps: add a channel with credentials, create a group with models and policy, then create an AccessKey for your app. The README warns that subscription OAuth clients use fixed callback ports, and the Compose file publishes them on the address set by HOST. If HOST is 0.0.0.0, those callback ports are exposed on all interfaces. Only one default Compose instance can run per host because the ports are fixed. That is a real operational constraint.

The 2.0 Migration Trap

The most important limitation in the README is the upgrade warning. It says: if you are using 1.x, read the migration section first, because 2.0 cannot open, import, or migrate 1.x data in place. That is a hard break. Anyone running GPT-Load 1.x must rebuild channels, groups, and AccessKeys from scratch, and historical logs or usage data will not carry over. The project is currently at v2.0.0-rc.11, so 2.0 itself is not stable. For a gateway that sits in front of production traffic, a release candidate plus a data migration dead end is a serious consideration. If you are on 1.x, the upgrade cost is not a simple docker pull; it is a reconfiguration project. If you are new, you avoid that pain, but you are adopting a pre-stable major version.

Alternatives and the Difference in Approach

The obvious alternative is a hosted gateway like LiteLLM or a commercial service such as OpenRouter. LiteLLM is also open source and supports many providers, but it focuses on API-key translation and a unified OpenAI-compatible interface. GPT-Load differs by treating subscription accounts as first-class citizens, with OAuth flows and quota windows built into the UI. OpenRouter is a managed relay that abstracts away individual credentials entirely; you pay one bill and never see upstream accounts. GPT-Load is the opposite: you bring your own credentials, including fragile subscription logins, and the gateway tries to keep them healthy. That is a meaningful difference. If you want to avoid the operational burden of managing subscription sessions, a hosted relay removes that problem. If you want to control which accounts carry your traffic, GPT-Load gives you that control at the cost of more setup and maintenance.

Maintenance, Licensing, and Operational Costs

The project is written in Go, which compiles to a single binary, and the README shows a Docker image on ghcr.io. The license is MIT, so you can modify and redistribute it without copyleft obligations. The repository is actively pushed, with release candidates coming out daily in early September 2026, which suggests rapid development but also that APIs and config may shift between release candidates. The embedded UI reduces the need to build your own dashboard, but you still need to maintain the underlying database (SQLite for small setups, MySQL or PostgreSQL for larger ones). Credential encryption is local, so you are responsible for key management. The fixed OAuth callback ports are a recurring cost: only one gateway instance per host by default, which limits horizontal scaling unless you customize the Compose file. There is no mention of multi-node clustering or shared state in the README, so assume a single instance is the supported topology.

Editorial conclusion

Adopt GPT-Load 2.0 if you run multiple LLM credentials, especially a mix of API keys and subscription logins, and want a single management UI with health checks and cost estimates. Do not adopt it if you need a drop-in replacement for a commercial gateway without reading the 2.0 migration notes, because 1.x data cannot be imported or migrated in place. Before committing, verify that your upstream providers are supported, that the fixed OAuth callback ports do not conflict with other services on your host, and that you are comfortable running a release candidate (v2.0.0-rc.11) in production. The project is MIT-licensed, actively pushed, but still pre-stable, so pin the exact image tag and test failover behavior with your own credentials before relying on it.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tbphp/gpt-load on GitHub