Choose your gateway setup

This page helps you pick a gateway configuration. Most teams need nothing beyond the first section; read the later ones when a specific need shows up.

Start with the default (most users)

Your organization already has a default gateway with transparent backends for Anthropic, OpenAI, and ChatGPT Codex traffic — what you get without doing anything. Everyone signs in with their own provider credentials, every session is captured, and there is nothing to set up.

Stay here as long as it works. The situations below are the reasons to move past it.

Add a gateway when you want separation

An organization can have several gateways, each with its own backends. Add one when you want traffic split along a boundary you care about:

• separate teams or projects whose model access should differ
• separate environments — for example a gateway for CI distinct from developers’ day-to-day traffic
• a place to try backend changes without touching the gateway everyone uses

Switching is cheap: the console Gateways page has a switcher, paperctl tapes gateway use <name> changes your local default, and paperctl start --gateway <name> <agent> routes a single launch without changing anything. See Manage gateways.

Transparent or managed credentials

Every backend authenticates to its provider one of two ways:

• Transparent — each person supplies their own provider credential (an API key in their environment, or their ChatGPT/Claude plan sign-in), and the gateway passes it through. Good default: no shared secret to manage, and people keep their existing accounts.
• Managed — your organization stores one provider key on the backend, and the gateway injects it into every request routed there. Choose this when you want one team key with one bill, or when you don’t want provider keys on individual laptops. Managed backends are also what gateway API keys need to fund inference.

Backends and providers shows how to set up both, including the team-managed OpenAI key for Codex.

paperd or direct access

There are two ways traffic reaches a gateway:

• Through paperd — the normal path. paperctl start <agent> (or shell routing) points the agent at the local daemon, which attaches your identity and forwards to the gateway. Use this for everything paperctl can launch or that can point at a local base URL.
• Directly, with a gateway API key — for CI jobs, scripts, and SDK code where paperd isn’t running. You call the gateway’s public endpoint with a per-user API key; capture still happens, because capture lives at the gateway. See API keys and direct access.

What gateways don’t do today

So you don’t design around something that isn’t there:

• No browser/CORS access — gateways serve server-side and CLI callers.
• No local-model routing — paperd forwards to your cloud gateway, not to models running on your machine.
• No content-based routing — a request’s backend is determined by its schema, the model allowlists, and your selection, not by analyzing the request.

Where to go next

• Manage gateways — create and switch gateways.
• Backends and providers — configure provider routes and credentials.
• API keys and direct access — call a gateway without paperd.