Skip to main content

What is Control Zero?

Control Zero is the governance layer for AI agents. You define what your agents are allowed to do, and Control Zero enforces it at runtime. On Claude Code, Gemini CLI, Cursor IDE, and Kiro CLI, a deny stops the tool call before it executes. Coverage is declared per event, so the audit trail never implies protection for a call path that was not covered. Kiro IDE is not an enforcement surface.

Hello World​

A real, runnable Python "hello world." No signup. No API key. No network.

pip install controlzero
# hello_controlzero.py
from controlzero import Client

# Define what your agent is allowed to do.
# Read operations: allowed. Write operations: blocked.
# Note: `database:query` and `database:execute` are legacy action names
# that remain supported. The canonical names are `database:read` and
# `database:write`; both forms match the same calls.
cz = Client(policy={
    "rules": [
        {"allow": "database:query",   "reason": "Reads are fine"},
        {"deny":  "database:execute", "reason": "No writes from this agent"},
    ]
})

# Your agent tries to read; allowed.
result = cz.guard("database", method="query", args={"sql": "SELECT id FROM orders"})
print(result.decision)   # "allow"

# Your agent tries to write; blocked before it ever runs.
result = cz.guard("database", method="execute", args={"sql": "DROP TABLE orders"})
print(result.decision)   # "deny"
print(result.reason)     # "No writes from this agent"

Run it:

$ python hello_controlzero.py
allow
deny
No writes from this agent

That's the whole loop. You wrote a policy, you called guard() before each tool call, and the SDK decided allow or deny. The denied call never happened. You wrote no enforcement code, no auth check, no allowlist logic.

Legacy and canonical action names both work

Both legacy (database:query, database:execute, database:delete) and canonical (database:read, database:write, database:admin) action names match the same calls. Use canonical names for new policies; existing rules with the legacy names continue to work without changes. See Policies for the full mapping.

The next step is moving the policy out of your code into the Control Zero dashboard so you can change it without redeploying. See Quickstart for the 5-minute version with the dashboard.

The problem it solves: AI agents call tools, run code, hit APIs, and access services through MCP. As they get more autonomous, you need guardrails with a clear, verifiable enforcement contract. Control Zero gives you one place to define those guardrails, deterministically blocks denied calls on enforcing surfaces, and records the coverage of each event. The capability matrix is derived from the SDK's own capability declarations; run controlzero coverage --json to export what your installed SDK actually declares (a bare controlzero coverage prints only a short per-host summary).

Why Control Zero​

  • Gateway proxy: A transparent drop-in proxy that governs LLM traffic with zero code changes. Change your base URL and you are done.
  • Local enforcement: Every action is evaluated against your policies without a per-call network round-trip.
  • Tool call interception: Every tool_use (Anthropic) and function_call (OpenAI) is evaluated against your policies. Denied calls are replaced inline before reaching your agent.
  • DLP detection, masking, and blocking: Detect or block sensitive data in prompts. On Claude Code and Gemini CLI, Python SDK hooks can redact matches in place and let the call proceed. On the coding-agent surfaces that cannot accept rewritten tool input -- Cursor, Kiro, Codex CLI, Antigravity -- a mask rule becomes a deny, so the secret never reaches the tool either way. The Gateway can mask, on both the request and the response path, but does neither by default: it detects. See Gateway for the two switches and which one a policy bundle can set.
  • Model blocking: Deny requests to unauthorized models at the gateway level.
  • Cost caps: Reject requests when estimated token cost exceeds your budget.
  • Secret injection: Store LLM provider keys in an encrypted vault. The SDK and gateway inject them at runtime.
  • Tamper detection: Policy bundles are encrypted at rest and cryptographically signed. A bundle that fails verification is never loaded, and the event is logged and reported. The SDK re-fetches its signing keys once in case they rotated; if verification still fails, the bundle is refused rather than trusted. During a background refresh the agent keeps enforcing the last known good policy; at startup there is nothing to fall back to, so calls are denied. See tamper detection.
  • Fail closed by default: When Control Zero cannot establish coverage, it denies rather than guesses. An unavailable policy bundle blocks traffic instead of silently allowing it.
  • Multi-provider support: Anthropic, OpenAI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, LangChain, CrewAI, and more.
  • Official SDKs: Python and Node.js. Install and wrap your AI client in two lines of code.
  • MCP server: Manage governance directly from AI coding clients like Claude Code, Cursor, and Windsurf.
  • MCP-native: First-class governance for MCP tool calls across any MCP-compatible client.
  • Complete audit trails: Every decision is logged with action, resource, result, timestamp, agent identity, and per-event coverage. “Did not run” is distinguishable from “ran and found nothing.”
  • Capability matrix from the code: The surface matrix is derived from the SDK's own capability declarations. controlzero coverage --json exports them for your installation, and it is the authority if this documentation ever disagrees. A bare controlzero coverage prints only a short per-host summary.
  • Free tier: 5,000 governed actions per month at no cost. No credit card required.

The Key Idea: Policies Live in the Dashboard, Not in Your Code​

This is the core design principle:

  • Policies are defined in the Control Zero dashboard (or via the API). They describe what actions are allowed or denied.
  • Your code calls tools through the SDK client. No references to specific policies, no action names hardcoded in your application.
  • The SDK handles enforcement automatically. Every guard() invocation is evaluated against the locally cached policy bundle.

You can change policies at any time in the dashboard without touching your code. Long-running SDK processes pick the change up on their next refresh: the Python SDK polls every 60 seconds by default, the Node SDK every 300 seconds. A manual refresh applies it immediately.

What Gets Enforced​

Every call made through guard() is checked against your active policies. The policy action is derived from the tool name and method you pass:

guard() argumentsPolicy action checked
guard("github", method="list_issues", ...)github:list_issues
guard("database", method="query", ...)database:query (canonical class: database:read)
guard("filesystem", method="write_file", ...)filesystem:write_file
guard("slack", method="post_message", ...)slack:post_message

You define policies using these tool:method action strings in the dashboard. The SDK evaluates them locally from a cached policy bundle, so each guard() call doesn't make a network request.

Architecture​

The flow:

  1. You define policies in the dashboard.
  2. The server compiles them into an encrypted, signed bundle.
  3. The SDK downloads the bundle once at startup, caches it locally.
  4. Every wrapped API call is checked against the locally cached policy. No network round-trip per call.
  5. Every decision (allow or deny) is logged for audit.

Enforcement Flow​

When your agent calls guard(), Control Zero checks the call against your policy and either allows it (your tool runs) or denies it (your tool never executes, and a PolicyDeniedError is raised).

Key Capabilities​

  • Gateway proxy: Transparent drop-in proxy for LLM traffic. Zero code changes required. Supports Anthropic, OpenAI, Google AI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, Mistral, and Cohere.
  • Local policy evaluation: Policies are evaluated locally with no per-call network round-trip.
  • Tool call interception: Every tool_use and function_call is evaluated and denied calls are replaced inline, in both streaming and non-streaming responses.
  • Pre-flight request guard: Model blocking, cost caps, and PII detection and blocking before requests reach the provider; Python SDK masking is supported only on Claude Code and Gemini CLI.
  • Fail closed by default: When coverage cannot be established, the decision is deny. An unavailable policy bundle blocks traffic instead of silently allowing it.
  • Signed policy bundles: Policy bundles are encrypted at rest and cryptographically signed. The SDK verifies every bundle before use and refuses to load one that fails verification. On a background refresh it keeps enforcing the last known good policy; at startup, with nothing verified to fall back to, it denies rather than running unguarded.
  • Offline enforcement: After the initial bundle download, SDK enforcement runs locally with no further network calls per request.
  • Secrets vault: Store LLM provider keys in an encrypted vault. Injected at runtime by the SDK and gateway.
  • Audit trail: Every decision is logged with action, resource, result, timestamp, token usage, agent identity, and per-event coverage. The record distinguishes “did not run” from “ran and found nothing.”
  • Capability claims come from the code: every capability claim traces to the adapters' own CoverageDecl declarations. A generated copy of the capability matrix lives in the SDK repository, where a CI drift gate fails the build if that page and the implementation disagree. That gate covers the generated page only -- these documentation pages are written by hand. Run controlzero coverage --json to export the declarations for your own installation; it is the authority if a page here ever disagrees.
  • Multi-provider: Anthropic, OpenAI, Ollama, DeepSeek, MoonshotAI, HuggingFace TGI, LangChain, CrewAI, and more.
  • Multi-language SDKs: Official SDKs for Python and Node.js.
  • MCP server: Manage governance directly from AI coding clients like Claude Code, Cursor, and Windsurf.
  • MCP tool control: Restrict which MCP servers and tools an agent can invoke.
  • Notification channels: Get alerts via Telegram, Slack, Email, Discord, or webhooks.

Next Steps​

The free tier includes 5,000 governed actions per month. No credit card required.

  • Quick Start: Get up and running in 5 minutes (gateway or SDK).
  • Gateway Proxy: Deploy the transparent proxy for zero-code governance.
  • Policies: Learn how to construct policies in the dashboard.
  • Pricing: Free, Solo, and Teams plans.
  • MCP Server: Manage governance from AI coding clients.
  • Integrations: OpenAI, Anthropic, Ollama, DeepSeek, LangChain, and more.
  • Blueprint Library: Implementation patterns for Enterprise SRE, HR, and Finance.
  • Guides: Build real applications with automatic policy enforcement.