Self-host New API: one gateway for Claude, OpenAI and Gemini, used by Claude Code and Codex

One teammate uses Claude Code, another uses Codex CLI, and someone else chats in Open WebUI. Each tool holds its own copy of a provider key, usage lands on separate bills, and nobody can say who used what or which key to revoke.

New API is an open-source model gateway. You put your OpenAI, Anthropic, Gemini and other provider keys behind it, then give each person or tool a key that New API issues, with its own models and quota. It serves the OpenAI Chat Completions, Responses, Anthropic Messages and Gemini formats, so common coding tools connect to it directly.

This guide uses Zenavo's New API template to run the gateway on a server you rent or own. The server, Zenavo and the upstream model APIs are billed separately; New API forwards and meters requests, it doesn't make model calls cheaper. New API focuses on issuing per-user keys and quotas for a team; if you mainly want protocol translation and failover for your own coding agents (Claude Code and Codex), see the lighter Magpie gateway.

Deploy New API

Connect a Linux server to Zenavo, open the New API template, choose the server and deploy.

The template currently sets up:

Setting	Value or purpose
Image	calciumion/new-api:latest
HTTP port	3000
Volume	/data, holding the default SQLite database and logs
SESSION_SECRET	Generated when the project is created; signs login sessions
TZ	UTC; change it to your time zone if you like

latest follows upstream. For long-term use, set a tag you have tested under Source in the service's Settings, and note it down.

Add a domain and finish setup right away

On the new-api service's Networking tab, bind a domain such as ai.example.com to port 3000, add an A record pointing to the server, and wait for HTTPS. See Domains & HTTPS.

The first visit opens New API's setup wizard, where you create the admin account. Once the gateway holds provider keys it can spend money, so finish the setup yourself as soon as the domain works, then check in the system settings whether new users may sign up on their own. For yourself and your team, turn public sign-up off and create accounts as the admin.

Add channels for your providers

New API calls each upstream connection a channel. On the Channels page, add one: pick the provider type, enter that provider's API key and the models to offer, save, then click Test to see a response.

A few tips:

• Enter provider keys only in channels, never in Zenavo variables, screenshots or chats.
• Name channels clearly, such as "Anthropic official", so logs are easy to read and channels easy to disable.
• Offer only the models you need. A model in the list isn't necessarily one your provider account may call.
• Use the provider's official API keys and follow its terms. Don't resell or share a personal chat subscription as an API.

Hand out keys and quotas

On the Tokens page, create a key for each person or tool, with the models, quota and expiry it gets. This sk- key is issued by New API: if it leaks, delete it here, without rotating the provider's key.

Issue keys per person and per tool, such as "Alex – Claude Code" and "Alex – Open WebUI". Usage stays easy to read, and revoking one doesn't break the others.

Connect Claude Code

Claude Code can send its requests to a custom Anthropic Messages endpoint through environment variables. On your computer:

export ANTHROPIC_BASE_URL="https://ai.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-new-api-token"
claude

Give ANTHROPIC_BASE_URL the domain only, without /v1: Claude Code adds /v1/messages itself. If the model names Claude Code asks for differ from the channel's, map them in the New API channel, or pick a model the gateway offers with /model in Claude Code. To also inspect logs, deploy, and roll back Zenavo services directly from Claude Code with MCP and Skills, see Deploy and debug Zenavo projects from Claude Code.

Connect Codex CLI

Codex CLI defines custom providers in ~/.codex/config.toml. Replace the model with one your channel offers:

model = "a-model-your-channel-offers"
model_provider = "newapi"

[model_providers.newapi]
name = "New API"
base_url = "https://ai.example.com/v1"
env_key = "NEWAPI_API_KEY"
wire_api = "responses"

Then run export NEWAPI_API_KEY="sk-…" and start codex. Unlike Claude Code, this base_url includes /v1.

Connect Open WebUI and LobeHub

If you run Open WebUI, open Settings → Admin → Connections and add an OpenAI-compatible connection: Base URL https://ai.example.com/v1, and as API key a token made just for Open WebUI. If you run LobeHub, point its provider setting or OPENAI_PROXY_URL at https://ai.example.com/v1 the same way.

When both are in the same Zenavo project (add New API to Open WebUI's project with Add Service → Templates), use the private network instead: http://new-api.zenavo.internal:3000/v1. Requests then never leave the server; see Private Networking.

Back up and upgrade

New API keeps its accounts, channels and tokens in the /data volume, including your provider keys, so guard its backups like the keys themselves.

In a maintenance window, stop the project, back up the volume from the new-api service's Backup & Restore tab, start the project again, and download a copy to keep. Before upgrading, read the release notes and back up first. If an upgrade changes the database schema, switching back to the old image may not undo it; restore the backup from before the upgrade instead.

FAQ

Claude Code returns 404 or can't connect? Check that ANTHROPIC_BASE_URL doesn't end in /v1, then look in New API's logs to see whether the request arrived and which model it asked for.

Codex says the model doesn't exist? The model in config.toml must be offered by a channel and allowed for the token. Also make sure wire_api is responses.

Does New API store conversations? It logs calls and usage; which fields depends on its version and settings. Requests still go to the upstream provider: running the gateway on your server doesn't keep the data on it.

Is a small server enough? New API itself is light; the load comes from concurrent requests. With many people streaming long answers at once, watch the server's memory and bandwidth.

Start from the New API template: finish setup and turn off public sign-up first, then add channels, issue tokens, and point your coding tools at it.