Gateway overview

When your agent calls a model, that request has to travel somewhere. With paper, it travels through your organization’s gateway — and that one routing decision is what makes everything else work: the request gets recorded, the right provider credential gets applied, and the session shows up in paper console for your whole team.

The mental model

Think of the gateway as your organization’s front door for model traffic. Every agent on the team sends its model calls to the same door instead of straight to Anthropic or OpenAI. Because all the traffic passes one point your organization controls, that point can do things no individual laptop can: record every session in one shared history, hold shared provider credentials, and decide which models are reachable.

That front door is the technical term gateway: a named, per-organization cloud route for model traffic. An organization can have several. Each gateway holds its own backends — a backend is one route from the gateway to a single provider, such as api.anthropic.com.

The request path

your agent (Claude Code, Codex, Pi)
   │  base URL points at localhost
   ▼
paperd — local daemon on your machine
   │  attaches your paper identity, forwards to the cloud
   ▼
gateway — your organization's route for model traffic
   │  records the session, picks the backend, applies credentials
   ▼
backend — one route to one provider
   ▼
provider (Anthropic, OpenAI, ...) → model

Each hop has one job:

• Your agent doesn’t change. paperctl start claude points its base URL at localhost; the agent behaves exactly as before.
• paperd runs on your machine at 127.0.0.1:51539. It keeps your login token fresh, stamps each request with your paper identity, and forwards it to your organization’s gateway. It is not a gateway — nothing is recorded or routed here.
• The gateway is where capture happens. It records the request and response as session data, then routes the call to a backend. Capture is fail-open: if recording ever has a problem, your request still reaches the provider.
• A backend names the provider route: the upstream host, the request schema the provider speaks, which models are allowed, and how the request is authenticated — with the caller’s own credential passed through (transparent) or with a key your organization stores on the backend (managed).
• paper console is where you see and manage all of this: the Gateways page shows each gateway, its backends, its provisioning status, and its endpoint; the API keys page holds your keys for direct access.

Two credentials, two jobs

Every request through a gateway carries up to two separate credentials, and keeping them apart makes the whole system easier to reason about:

• Your paper identity says who is making this request — it’s what lets the gateway record the session under your name in your organization. paperd attaches it automatically; for direct access a gateway API key carries it instead.
• The provider credential says who pays for the model call — an Anthropic or OpenAI key, or a ChatGPT/Claude plan login. On a transparent backend it comes from you and passes through untouched. On a managed backend the gateway injects a key your organization stores.

What you get without doing anything

When your organization is created, paper provisions a default gateway with three transparent backends:

All three accept any model name and pass your own credentials through. That’s why the quickstart never mentions setup: paperctl login discovers the default gateway, and paperctl start claude just works.

When you’ll touch the gateway

You configure gateways when your team’s needs outgrow the default:

• Separate traffic by team, environment, or project → create another gateway
• Stop distributing provider keys to every laptop → a managed backend with a shared team key
• Control which models the team can call → model allowlists on backends
• Send traffic from CI, scripts, or tools paperctl doesn’t wrap → gateway API keys and direct access

Choose your setup walks through which of these applies to you.

Where to go next

• Choose your setup — decide which gateway configuration fits your team.
• Manage gateways — create, inspect, switch, and delete gateways from the console or CLI.
• How capture works — what actually ends up in a session.