Gateway Proxy

Control Zero Gateway is a transparent proxy that sits between your AI agents and LLM providers. It intercepts every request, evaluates tool calls against your policies, and blocks unauthorized actions, all without changing your agent's code.

How It Works

The gateway operates in two phases:

Pre-flight (request guard): Before forwarding to the LLM, the gateway checks model blocking rules, estimates cost against budget caps, and scans for PII in prompts.
Response interception: After the LLM responds, every tool_use (Anthropic) or function_call (OpenAI) block is evaluated against your policies. Denied tool calls are replaced inline with a policy denial message. Both streaming and non-streaming responses are supported.

Quick Start

Change your LLM provider base URL to point to the Control Zero gateway:

Anthropic (Claude)

# Before
ANTHROPIC_API_URL=https://api.anthropic.com

# After
ANTHROPIC_API_URL=https://gateway.controlzero.ai

Add the required headers:

X-ControlZero-Agent-ID: my-agent
X-ControlZero-API-Key: cz_live_xxx

OpenAI

# Before
OPENAI_API_BASE=https://api.openai.com

# After
OPENAI_API_BASE=https://gateway.controlzero.ai/v1

Add the same Control Zero headers as above.

That is it. No SDK installation, no code changes. Your existing agent code keeps working. The gateway enforces your policies transparently.

Features

Pre-flight Request Guard

Before forwarding to the LLM provider, the gateway runs these checks:

Model blocking: Deny requests to unauthorized models (e.g., block agents from using expensive models).
Cost estimation: Reject if estimated token cost exceeds your budget cap.
PII detection: Detect, mask, or block PII in prompts. Configurable via CZ_GATEWAY_PII_ACTION (detect, mask, or block).

If the policy engine is unavailable and fail_closed is enabled (the default), all requests are blocked. No silent failures.

Tool Call Interception

After the LLM responds:

Every tool_use block (Anthropic) or function_call (OpenAI) is evaluated against your policies.
Denied tool calls are replaced inline with a policy denial message.
Each decision is logged separately for auditing.
Both streaming and non-streaming responses are supported.

Supported Providers

Provider	Gateway Path	Protocol
Anthropic (Claude)	`/v1/messages`	Anthropic Messages API
OpenAI (GPT)	`/v1/chat/completions`	OpenAI Chat Completions
Ollama	`/ollama/v1/chat/completions`	OpenAI-compatible
DeepSeek	`/deepseek/chat/completions`	OpenAI-compatible
MoonshotAI	`/moonshot/v1/chat/completions`	OpenAI-compatible
HuggingFace TGI	`/huggingface/v1/chat/completions`	OpenAI-compatible (no tool interception)

Ollama, DeepSeek, MoonshotAI, and HuggingFace are disabled by default. Enable them with environment variables:

CZ_GATEWAY_OLLAMA_ENABLED=true
CZ_GATEWAY_DEEPSEEK_ENABLED=true
CZ_GATEWAY_MOONSHOT_ENABLED=true
CZ_GATEWAY_HUGGINGFACE_ENABLED=true

Identity and Context Headers

Header	Required	Description
`X-ControlZero-Agent-ID`	Yes	Identifies the agent making the call
`X-ControlZero-API-Key`	Yes	Control Zero API key (`cz_live_` or `cz_test_`)
`X-ControlZero-Identity-Token`	Optional	JWT with user claims for principal resolution
`X-ControlZero-User-ID`	Optional	User identifier for policy scoping
`X-ControlZero-User-Group`	Optional	User group for RBAC policy evaluation

Fail-Closed Mode

If the gateway cannot reach the Control Zero backend, or the policy bundle is expired or tampered with, it blocks ALL requests by default. This is controlled by the CZ_GATEWAY_FAIL_CLOSED setting (default: true).

The gateway also runs periodic integrity self-checks on the loaded policy bundle (configurable via CZ_GATEWAY_INTEGRITY_CHECK_INTERVAL_SECONDS, default: 60s). If the bundle checksum fails, traffic is blocked and an alert is sent.

Tamper Detection

Policy bundles are encrypted at rest and cryptographically signed. The gateway verifies the signature and checksum on every load and at regular intervals. Tampering triggers fail-closed mode and an alert.

Audit Logging

Every proxied request is logged to the immutable audit trail with:

Provider, model, and token usage
Tool calls detected in the response
Policy decisions (allow/deny) for each tool call
Latency, status codes, and error information
Agent ID and user identity context

Self-Hosted Deployment

The gateway runs as a Docker container:

docker run -d \
  -p 8000:8000 \
  -e CZ_GATEWAY_CZ_API_KEY=cz_live_xxx \
  -e CZ_GATEWAY_CZ_BACKEND_URL=https://api.controlzero.ai \
  -e CZ_GATEWAY_ANTHROPIC_API_KEY=sk-ant-xxx \
  -e CZ_GATEWAY_OPENAI_API_KEY=sk-xxx \
  controlzero/gateway:latest

Environment Variables

All gateway settings use the CZ_GATEWAY_ prefix:

Variable	Default	Description
`CZ_GATEWAY_CZ_API_KEY`	(required)	Your Control Zero API key
`CZ_GATEWAY_CZ_BACKEND_URL`	`http://control-zero-backend:8080`	Control Zero backend URL
`CZ_GATEWAY_ANTHROPIC_API_URL`	`https://api.anthropic.com`	Anthropic upstream URL
`CZ_GATEWAY_ANTHROPIC_API_KEY`	(empty)	Anthropic API key (injected if set)
`CZ_GATEWAY_OPENAI_API_URL`	`https://api.openai.com`	OpenAI upstream URL
`CZ_GATEWAY_OPENAI_API_KEY`	(empty)	OpenAI API key (injected if set)
`CZ_GATEWAY_FAIL_CLOSED`	`true`	Block all traffic when policies unavailable
`CZ_GATEWAY_ENFORCE_TOOL_POLICIES`	`true`	Enforce policies on tool calls (`false` = shadow mode)
`CZ_GATEWAY_ENFORCE_LLM_POLICIES`	`true`	Enforce pre-flight checks (model/cost/PII)
`CZ_GATEWAY_PII_ACTION`	`detect`	PII handling: `detect`, `mask`, or `block`
`CZ_GATEWAY_POLICY_REFRESH_INTERVAL_SECONDS`	`300`	How often to re-pull policies
`CZ_GATEWAY_POLICY_MAX_AGE_SECONDS`	`86400`	Max bundle age before fail-closed
`CZ_GATEWAY_ALERT_WEBHOOK_URL`	(empty)	Slack webhook for tamper/failure alerts
`CZ_GATEWAY_PORT`	`8000`	Gateway listen port

Shadow Mode

Set CZ_GATEWAY_ENFORCE_TOOL_POLICIES=false to run in shadow mode. The gateway evaluates every tool call against policies and logs the decision, but does not modify responses. Use this to audit what would be blocked before enabling enforcement.

Docker Compose

services:
  cz-gateway:
    image: controlzero/gateway:latest
    ports:
      - '8000:8000'
    environment:
      CZ_GATEWAY_CZ_API_KEY: cz_live_xxx
      CZ_GATEWAY_CZ_BACKEND_URL: https://api.controlzero.ai
      CZ_GATEWAY_ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
      CZ_GATEWAY_OPENAI_API_KEY: ${OPENAI_API_KEY}
    restart: unless-stopped

Gateway vs SDK

	Gateway	SDK
Code changes	None. Change base URL only	Install package, wrap tool calls
Works with	Any agent that calls LLM APIs	Python, Node.js, Go
Enforcement point	Network layer (proxy)	Application layer (in-process)
Latency	Network hop to gateway	Sub-3ms local evaluation
Best for	Existing agents, quick rollout	New agents, tightest integration

Both approaches enforce the same policies defined in your dashboard. You can use them together. The gateway handles LLM-level enforcement while the SDK handles application-level tool governance.

Next Steps

Quick Start: Get up and running in 5 minutes.
Policies: Learn how to write policies.
MCP Tool Control: Govern MCP server and tool access.
CLI Scanner: Scan projects for governance gaps in CI/CD.

How It Works​

Quick Start​

Anthropic (Claude)​

OpenAI​

Features​

Pre-flight Request Guard​

Tool Call Interception​

Supported Providers​

Identity and Context Headers​

Fail-Closed Mode​

Tamper Detection​

Audit Logging​

Self-Hosted Deployment​

Environment Variables​

Shadow Mode​

Docker Compose​

Gateway vs SDK​

Next Steps​