AgentGuard

The firewall for AI agents.
Every tool call, every API call — gated by policy, logged, and routed for human approval. No opt-out path.

Quickstart • Why AgentGuard • Architecture • Limitations & Threat Model • Production • Docs • Contributing

AgentGuard Cloud (preview)

AgentGuard Cloud is the hosted, multi-tenant version — same policy engine, same audit log, run for you. Currently in design. Join the waitlist at https://agentguard.lictorate.com. The self-hosted Apache-2.0 build in this repo will always remain fully featured.

The Problem

Every trending AI project is giving agents more autonomy — running shell commands, browsing the web, calling APIs, moving money, even performing penetration tests. But nobody is building the guardrails.

Right now, most teams deploying AI agents are just... hoping they behave. AgentGuard fixes that.

Why AgentGuard

AgentGuard is the wire-level checkpoint that sits between your agent and everything it touches:

• Policy-gated tool calls. Every shell command, file write, network call, browser action, or model spend evaluated against a YAML policy before it runs.
• Human-in-the-loop approvals. Risky actions pause, ping Slack/webhooks, surface on a live dashboard, and resume only after a human says yes.
• Append-only audit trail. JSON-Lines log of every decision with agent ID, scope, command, timestamp, and reasoning — queryable by CLI, dashboard, or Prometheus metrics. For tamper-evidence, forward it to append-only / WORM storage (S3 Object Lock, a SIEM, or syslog) — AgentGuard does not cryptographically seal the log itself.
• Per-agent, per-environment, per-tool scoping. One policy file, finely overridable for each agent identity.

Quickstart

AgentGuard ships three integration paths, listed from "no code change" to "deepest control":

1. MCP Gateway

For Claude Desktop and any MCP-aware client (Cursor, Cline, Continue, Zed), point your config at agentguard-mcp-gateway and every tools/call from the model is policy-checked before reaching the real MCP server:

go install github.com/Caua-ferraz/AgentGuard/cmd/agentguard-mcp-gateway@latest

Then add the gateway to claude_desktop_config.json — copy the ready-made block from the 90-second walkthrough in docs/QUICKSTART_MCP.md or from examples/claude-desktop-config.json. Ready configs for Cursor, Cline, Continue, Zed: examples/. Wire-format design + client-integration gotchas: docs/MCP_GATEWAY.md.

2. LLM API Proxy

For any code that already uses the OpenAI / Anthropic SDKs, set one environment variable and your existing client flows through AgentGuard:

go install github.com/Caua-ferraz/AgentGuard/cmd/agentguard-llm-proxy@latest

agentguard-llm-proxy \
    --listen 127.0.0.1:8081 \
    --policy configs/default.yaml \
    --guard-url http://127.0.0.1:8080 \
    --api-key "$AGENTGUARD_API_KEY" &

export OPENAI_BASE_URL=http://127.0.0.1:8081/v1
# Anthropic SDK: ANTHROPIC_BASE_URL=http://127.0.0.1:8081 (no /v1 suffix)

Tool calls inside the response stream are intercepted, gated against your policy, and either flushed to your code byte-identically (ALLOW), rewritten as a synthetic refusal (DENY), or surfaced for human approval (REQUIRE_APPROVAL). The OpenAI / Anthropic SDKs do not need to know the proxy exists.

90-second walkthrough: docs/QUICKSTART_LLM_PROXY.md. Wire-format design + client-integration gotchas: docs/LLM_API_PROXY.md. Ready scripts for the OpenAI SDK, Anthropic SDK, LangChain, and CrewAI: examples/.

3. SDK (compatibility tier)

The Python and TypeScript SDKs remain fully supported for direct callers and for code paths where the proxy isn't practical (offline tools, embedded scripts, custom transports). They opt in via an explicit Guard.check(...) call:

pip install agentguardproxy

from agentguard import Guard

guard = Guard("http://localhost:8080", agent_id="my-bot")

result = guard.check("shell", command="rm -rf ./old_data")
# result.decision = "REQUIRE_APPROVAL"
# result.approval_url = "http://localhost:8080/v1/approve/ap_..."

if result.allowed:
    execute(command)

TypeScript/Node.js:

import { AgentGuard } from '@agentguard/sdk';

const guard = new AgentGuard({ baseUrl: 'http://localhost:8080', agentId: 'my-bot' });
const result = await guard.check('network', { url: 'https://api.production.internal/deploy' });

The SDKs are not deprecated. They are the right answer when you control the agent's source and want explicit, scope-tagged check points. Polling for approval, decorators/HOFs, cost guardrails, framework adapters (LangChain, CrewAI, browser-use, MCP): docs/SDK_PYTHON.md • docs/ADAPTERS.md.

Install the server

# From source
git clone https://github.com/Caua-ferraz/AgentGuard.git
cd AgentGuard && go build -o agentguard ./cmd/agentguard

# Or via Go install
go install github.com/Caua-ferraz/AgentGuard/cmd/agentguard@latest

# Or Docker (build the image from the repo's Dockerfile first)
docker build -t agentguard:latest .
docker run -d -p 8080:8080 \
  -v agentguard-audit:/var/lib/agentguard \
  agentguard:latest

Prerequisites: Go 1.25+, Python 3.10+ (optional, for the SDK; 3.8 and 3.9 are unsupported — upstream EOL October 2024 and October 2025). See docs/SETUP.md for details.

Minimal policy

configs/default.yaml — a ready-to-use default ships in the repo. A minimal example:

version: "1"
name: "development-sandbox"
rules:
  - scope: shell
    require_approval:
      - pattern: "sudo *"
      - pattern: "rm -rf *"
    allow:
      - pattern: "ls *"
      - pattern: "cat *"
  - scope: network
    allow:
      - domain: "api.openai.com"
      - domain: "api.anthropic.com"

Full schema (filesystem, cost, per-agent overrides, rate limits, conditional rules, notifications): docs/POLICY_REFERENCE.md.

Start the server

agentguard serve --policy configs/default.yaml --dashboard --watch

CLI flags and subcommands: docs/CLI.md.

Architecture

AgentGuard is the wire-level checkpoint between your agent and everything it touches. The checkpoint runs at three layers; all three share one policy, one audit log, one approval queue.

   Claude Desktop / Cursor /         ┌──────────────────────┐
   Cline / Continue / Zed   ───────▶ │ agentguard-mcp-      │ ─┐
                                     │ gateway              │  │
                                     └──────────────────────┘  │
                                                               │     ┌──────────────────┐
   OpenAI / Anthropic                ┌──────────────────────┐  │     │ AgentGuard server│
   SDK code                 ───────▶ │ agentguard-llm-proxy │ ─┼───▶│ (agentguard      │
   (OPENAI_BASE_URL,…)               │                      │  │     │  serve)          │
                                     └──────────────────────┘  │     ├──────────────────┤
                                                               │     │ policy · audit · │
   Custom code (LangChain,           ┌──────────────────────┐  │     │ approvals ·      │
   CrewAI, browser-use,     ───────▶ │ Python / TypeScript  │ ─┘     │ dashboard        │
   custom)                           │ SDK + adapters       │        └──────────────────┘
                                     └──────────────────────┘

Rule precedence: deny → require_approval → allow → default deny. Policy scopes: shell, filesystem, network, browser, cost, data, mcp_tool (plus the unmapped sentinel emitted by the LLM API Proxy when a tool call has no tool_scope_map entry). See docs/POLICY_REFERENCE.md. Architecture deep-dive: docs/PROXY_ARCHITECTURE.md.

Limitations & Threat Model

AgentGuard is a policy enforcement and audit layer. It is not an OS sandbox. Read this before you trust it as your last line of defense.

• Two of the three layers are wire-level. The MCP Gateway and LLM API Proxy sit between the agent and its tools / model. There is no opt-out short of pointing the client at a different MCP server or ignoring the SDK's base-URL configuration. Operators who control the agent's environment (env vars, network egress, MCP client config) get an enforcement boundary, not just an advisory one.
• The SDK layer is opt-in. The agent must call guard.check(...) (directly, via @guarded, or via a framework adapter) — that makes it advisory. Use it when the wire-level layers are impractical (offline scripts, custom transports); pair it with the gateway / LLM proxy whenever both apply.
• AgentGuard does not sandbox the host or intercept syscalls. A determined agent that controls its own runtime can bypass AgentGuard by ignoring OPENAI_BASE_URL, talking to a different MCP server, or shelling out directly. Combine AgentGuard with OS-level isolation (containers, seccomp, AppArmor, network egress rules) when the threat model includes a hostile agent.
• Pattern matching is string-glob, not semantic. A deny rule for rm -rf * matches literal strings; an agent (or a creative human) can substitute equivalents (find / -delete, base64 payloads, etc.). Treat policies as a high-signal first filter, not a complete authorization model. A single * also matches across /, so an ALLOW path pattern like /workspace/* grants the whole subtree (/workspace/a/b/secret.env), not just the top level — bound path allows with **. See docs/POLICY_REFERENCE.md.
• The MCP Gateway brokers tools only. It gates tools/call and aggregates tools/list, but it does not route resources/* or prompts/* (those capabilities are masked out of the handshake, not advertised), does not support server-initiated requests (sampling/createMessage, roots/list, elicitation/create from a downstream are dropped, never forwarded to the host), and treats notifications/cancelled as a best-effort no-op. A downstream MCP server that depends on those flows has its tools gated normally while those specific features silently do nothing. Streamable-HTTP transport is not implemented — the gateway is stdio-only on both sides. See docs/MCP_GATEWAY.md.
• Single-node by default; multi-node via PostgreSQL (v1.0). With the default SQLite store, the approval queue, rate-limiter, and cost accumulators persist locally and survive restarts (write-behind, off the hot path) but are per-instance. Point --store-dsn at PostgreSQL and give each replica a --node-id to share that state across replicas. Two honesty notes on the shared mode: distributed rate/cost limiting is bounded-overshoot, not globally strict — worst-case admissions can exceed a limit by ≈ reconcile-interval × peak rate per additional replica, a deliberate trade that keeps synchronous database calls off the enforcement hot path — and cross-node approval state converges within one --reconcile-interval (default 2s): an approval consumed on one node is spent cluster-wide once reconciled, and conflicting resolutions always converge to DENY. Set --persist=false for the legacy pure-in-memory behavior.

Dashboard

Live SSE action feed, one-click approve/deny, running totals, agent context. Start with --dashboard and open http://localhost:8080/dashboard. Walkthrough: docs/DASHBOARD.md.

Production

Running AgentGuard in production? The four most common misconfigurations — no API key (→ localhost-only bind), missing --tls-terminated-upstream behind an HTTPS proxy, wrong --base-url, and unmounted audit volume — all have one-line fixes. Work through the checklist below before exposing AgentGuard beyond localhost.

• Set --api-key (or AGENTGUARD_API_KEY). Without it, AgentGuard binds to 127.0.0.1 only.
• Set --base-url to the public URL. Otherwise Slack/webhook approval links point at http://localhost:8080.
• Pass --tls-terminated-upstream if TLS is terminated upstream, or the dashboard login loops.
• Set --allowed-origin to your frontend's exact origin.
• Mount a writable volume for the audit log — no mount, log lost on restart.
• Running more than one replica? Use PostgreSQL. On the default SQLite store, rate-limit buckets and session-cost accumulators are per-instance; replicas: > 1 lets an agent burst past per-scope limits. Set --store-dsn postgres://… plus a distinct --node-id per replica for shared state (bounded-overshoot limits — see docs/OPERATIONS.md).

Full reference configs (nginx + Docker Compose + Kubernetes), auth/CORS/TLS details, and day-2 operations: docs/DEPLOYMENT.md • docs/OPERATIONS.md • docs/TROUBLESHOOTING.md.

Documentation

Roadmap

Where things stand (v1.0)

Everything in the pitch above is shipped: the policy engine with all seven scopes, the three enforcement paths (MCP Gateway and LLM API Proxy since v0.5, SDKs + adapters throughout), audit logging with default-on rotation, the approval queue + dashboard, cost guardrails, rate limiting, persistent state and multi-tenant policies on a zero-config SQLite store (v0.6), cross-transport verdict consistency and outage durability (v0.7), the v0.9 surface stabilization with a CI-enforced p99 latency gate, and the v1.0 PostgreSQL multi-node backend — shared approvals / rate-limit / cost state across replicas via background reconcile, with the hardened approval lifecycle (write-once resolutions, one-shot time-boxed ALLOWs) enforced cluster-wide. The release-by-release detail lives in CHANGELOG.md; the frozen surfaces and the v1.x additive-only promise are in docs/COMPATIBILITY.md.

Planned

• Policy-as-code (test policies in CI/CD)
• Multi-agent session correlation
• Session replay in dashboard
• Policy editor in dashboard
• AutoGPT adapter
• OpenAI Agents SDK adapter
• SOC 2 / compliance report generation
• VS Code extension for policy authoring

Contributing

See CONTRIBUTING.md. Priority areas: adapters for more agent frameworks, new scope types and matching strategies, dashboard UI, documentation.

License

Apache 2.0 — see LICENSE.

Stop hoping your agents behave. Start knowing.