Gateway Basics

This page follows a single request from an agent to an LLM provider and back, then covers the agent lifecycle and the limits of what the gateway does.

One request, step by step

A developer runs viper claude and asks Claude Code to fix a failing test. Claude Code sends a request to the Anthropic API. Here is what happens to it.

1. Viper captures the agent’s state. When the session starts, Viper records the agent’s configuration files: its settings, skills, and permissions. For every request it then builds a state snapshot from that configuration and the agent’s runtime state, such as its workspace and selected environment variables. For Claude Code and Codex the snapshot also covers the request’s model, tools, and system prompt, so it can change within a session.
2. Viper signs the request. Viper signs the request with the agent’s private key, which never leaves the machine. The signature covers the request body and a reference to the state snapshot, so neither can be changed in transit. If Viper cannot sign a request, it does not send it.
3. The gateway verifies identity. The gateway checks the signature, confirms the request is fresh and not a replay, and looks up the signing key. The key must belong to a registered agent that has not been revoked.
4. The gateway resolves the project. If the agent presents a project membership (issued when the agent is associated with a project in Guardian), the project trust and project membership plugins run as part of this step to confirm the project and the membership are valid, and the request is treated as work for that project. An agent that presents no membership runs under your organization-wide settings only.
5. Policy plugins run. The gateway runs the remaining policy plugins in order. The global configuration is the organization-wide floor and always applies. If the request belongs to a project with its own configuration, that project layer runs on top. Any plugin in enforce mode can deny the request, and a few plugin stages run earlier (before identity is verified) or later (when the response starts).
6. The gateway forwards the request. An allowed request goes to the provider with the agent’s own provider credentials, exactly as the agent sent them.
7. The gateway records the exchange. The request, the response, the decision, the plugin results, and the state snapshot reference are stored as an audit exchange.
8. The response returns. The provider’s response streams back through the gateway and Viper to the agent. From the agent’s point of view, it talked to the provider.

If the gateway denies a request at step 3, 4, or 5, the agent receives an error with a short reason code, and the denied exchange is still recorded. See Audit Trail.

When a developer turns on egress capture, Viper can also relay the agent’s other HTTP traffic (not only LLM calls) through the gateway, where it is recorded the same way.

Agent lifecycle

Every agent moves through the same stages.

1. Register. A user with the Register Agents permission enrolls the agent. The Guardian Platform mints the agent ID and binds the agent to that user. See Register Agents.
2. Associate with a project. In the Agent Catalog, a Project Owner or Organization Owner associates the agent with a project. Until then the agent can send traffic, but project views do not show it and project policies do not apply to it.
3. Operate. The developer runs the agent through Viper. Each request is verified, checked, and recorded, and each state snapshot is added to the agent’s history.
4. Revoke or restore. An Organization Owner can revoke the agent at any time. The gateway rejects the agent’s next request. Restoring the agent re-enables it. See Agent Inventory.

What the gateway does not do

• It does not hold provider API keys. Your agents keep using their own Anthropic or OpenAI credentials, and those credentials pass through the gateway unchanged. You manage provider accounts and keys the same way you do today. Credential headers are redacted when anyone views an exchange in Guardian.
• It does not modify the agent’s prompts. The gateway allows or denies a request. It does not rewrite what the agent sends or what the provider returns.
• It does not see traffic that bypasses Viper. An agent started without Viper, or configured to call a provider directly, is invisible to the gateway. Viper refuses to start some agents when their configuration would send part of their traffic around it. See Run Agents.

Provider routes

The gateway forwards to three provider routes. Viper picks the right one for each agent.

OpenClaw can use all three routes at once. On the Viper side that means four local proxies, one per provider family (Anthropic, OpenAI API, ChatGPT backend, and ChatGPT Codex backend); the last two both land on the gateway’s ChatGPT backend route.

Related

• Agent Gateway — what the gateway gives your organization and where to start
• Gateway Policies — hook stages, modes, and how global and project layers combine
• Audit Trail — recorded exchanges and the reason codes for denied requests
• Register Agents — enroll an agent so the gateway accepts its key
• LLM Gateway Architecture — the gateway service’s endpoints, signing checks, and storage
• Run Agents — start each agent through Viper so its traffic reaches the gateway