Manage gateways

This page covers creating, inspecting, switching, and deleting gateways. You’ll need it when one gateway per organization stops being enough — Choose your setup covers when that is.

Before you start: you need a paper console account and an organization, and for the CLI commands an authenticated paperctl.

In paper console

The Gateways page (in the console sidebar) is the management surface:

• The gateway list on the left shows every gateway in your organization with its status. Selecting one shows its details.
• Create gateway provisions a new one. Names are lowercase letters, digits, and hyphens (they become part of a DNS name).
• The detail view shows the gateway’s endpoint — the public URL traffic reaches it at — and its backends. (API keys for direct access live on their own console page.)
• Delete removes a gateway and its backends. Sessions already captured are not affected; they live in your organization’s history, not on the gateway.

Provisioning status

A gateway is real infrastructure, so it doesn’t exist instantly. The status badge moves through Pending and Provisioning before reaching Running; backends similarly show Pending until they’re ready. The page polls while anything is still provisioning.

Traffic only flows on a Running gateway with a ready backend. A Failed state won’t repair itself — delete the gateway or backend and recreate it, and contact support if it fails twice.

Know what delete-and-recreate costs before doing it on a gateway people use: deleting a gateway removes its backends with it, including any managed provider keys stored on them, so you’ll recreate the backends (re-entering managed keys — paper doesn’t keep a copy) and wait for the replacement to provision before traffic flows again. Anyone routing through that gateway is interrupted until it’s back to Running with ready backends. Captured sessions are unaffected either way. On a shared gateway, prefer recreating under a new name and switching people over, so the old one keeps serving until the replacement is ready — that choice only exists before you delete.

From the CLI

The gateway commands live under the paperctl tapes namespace (tapes is the capture engine behind gateways — the namespace groups everything about the capture route):

paperctl tapes gateway list             # every gateway in the active org
paperctl tapes gateway get <name>       # one gateway's details, including its endpoint
paperctl tapes gateway create --name <name>
paperctl tapes gateway delete <name>    # asks for confirmation; --yes skips it

paperctl tapes create runs an interactive wizard that creates a gateway and its first backend in one pass.

Which gateway your traffic uses

Your machine routes through one primary gateway, recorded in paperd’s local config (~/.config/paper/daemon.toml). That file is a cache of what the cloud knows — paperctl tapes gateway list refreshes it.

paperctl status                         # shows the active org, gateway, and route
paperctl tapes gateway use <name>       # make <name> the primary gateway

gateway use is a local operation: it flips the primary flag in your daemon config and signals paperd to re-read it. Nothing changes in the cloud, and nothing changes for teammates.

To route one agent launch through a different gateway without touching your primary:

paperctl start --gateway <name> claude

Add --backend <name> when the gateway has more than one backend that could serve the launch.

Verify it worked

After creating or switching:

paperctl status

The output names the gateway paperd routes through. Run a short agent session and confirm it appears in paperctl sessions list — the session is the proof the route works end to end.

Where to go next

• Backends and providers — add provider routes to your gateway.
• API keys and direct access — call the gateway without paperd.
• CLI troubleshooting — including gateway status and auth failures.