The firewall for AI agents.
Policy enforcement, real-time oversight, and full audit logging for autonomous AI systems.
Quickstart • Why AgentGuard • Architecture • Production • Docs • Contributing
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.
| Without AgentGuard | With AgentGuard |
|---|---|
Agent runs rm -rf / — you find out later |
Policy blocks destructive commands before execution |
| Agent calls production API with no oversight | Action paused, you get a Slack/webhook notification to approve |
| No record of what the agent did or why | Full audit trail with timestamps, reasoning, and decisions |
| "It worked on my machine" debugging | Query any agent session from the audit log |
| One policy for all agents | Per-agent, per-environment, per-tool permission scoping |
# 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
docker run -d -p 8080:8080 \
-v agentguard-audit:/var/lib/agentguard \
agentguard:latestPrerequisites: Go 1.22+, Python 3.8+ (optional, for the SDK). See docs/SETUP.md for details.
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.
agentguard serve --policy configs/default.yaml --dashboard --watchCLI flags and subcommands: docs/CLI.md.
pip install agentguardproxyfrom 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' });Polling for approval, decorators/HOFs, cost guardrails, framework adapters (LangChain, CrewAI, browser-use, MCP): docs/SDK_PYTHON.md • docs/ADAPTERS.md.
┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────┐
│ AI Agent │────▶│ AgentGuard Proxy │────▶│ Target │
│ (any framework)│◀────│ │◀────│ (tools, │
│ │ │ ┌──────────────────────┐ │ │ APIs, │
│ • LangChain │ │ │ Policy Engine │ │ │ shell) │
│ • CrewAI │ │ ├──────────────────────┤ │ └─────────────┘
│ • browser-use │ │ │ Rate Limiter │ │
│ • Claude (MCP) │ │ ├──────────────────────┤ │ ┌─────────────┐
│ • Custom │ │ │ Approval Queue │ │────▶│ Dashboard │
│ │ │ ├──────────────────────┤ │ │ (web UI) │
│ │ │ │ Notifier (Slack/WH) │ │ └─────────────┘
│ │ │ ├──────────────────────┤ │
│ │ │ │ Audit Logger │ │ ┌─────────────┐
│ │ │ └──────────────────────┘ │────▶│ Audit Log │
└─────────────────┘ └──────────────────────────┘ │ (JSON) │
└─────────────┘
Rule precedence: deny → require_approval → allow → default deny. Scopes: filesystem, shell, network, browser, cost. See docs/POLICY_REFERENCE.md.
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.
Running AgentGuard in production? The four most common misconfigurations — no API key (→ localhost-only bind), missing
--tls-terminated-upstreambehind an HTTPS proxy, wrong--base-url, and unrotated audit log — all have one-line fixes. Work through the checklist below before exposing AgentGuard beyond localhost.
- Set
--api-key(orAGENTGUARD_API_KEY). Without it, AgentGuard binds to127.0.0.1only. - Set
--base-urlto the public URL. Otherwise Slack/webhook approval links point athttp://localhost:8080. - Pass
--tls-terminated-upstreamif TLS is terminated upstream, or the dashboard login loops. - Set
--allowed-originto your frontend's exact origin. - Mount a writable volume for the audit log — no mount, log lost on restart.
- Plan audit log rotation externally (AgentGuard does not rotate
audit.jsonl). - Stay on
replicas: 1— rate-limit buckets and session-cost accumulators are per-instance.
Full reference configs (nginx + Docker Compose + Kubernetes), auth/CORS/TLS details, and day-2 operations: docs/DEPLOYMENT.md • docs/OPERATIONS.md • docs/TROUBLESHOOTING.md.
AgentGuard is a policy enforcement layer, not a sandbox.
- Shell scope uses string-glob matching, not semantic analysis. A deny rule for
rm -rf *matches literal strings; determined agents can bypass with equivalents (find / -delete, base64 payloads, etc.). Combine with OS-level sandboxing (containers, seccomp, AppArmor) for strong isolation. - AgentGuard is opt-in, not a transparent proxy. The agent must call
/v1/checkbefore acting. It is an advisory gate, not an enforcement boundary. - Audit log is append-only JSON lines. No built-in rotation, retention, or tamper detection.
- Approval queue and rate-limiter state are in-memory. Both reset on restart and are not shared across instances.
| Topic | Doc |
|---|---|
| Getting started | docs/SETUP.md |
| Policy YAML schema + gotchas | docs/POLICY_REFERENCE.md |
| HTTP API | docs/API.md |
| CLI reference | docs/CLI.md |
| Python SDK | docs/SDK_PYTHON.md |
| Framework adapters (LangChain, CrewAI, browser-use, MCP) | docs/ADAPTERS.md |
| Dashboard walkthrough | docs/DASHBOARD.md |
| Approval workflow end-to-end | docs/APPROVAL_WORKFLOW.md |
| Deployment / TLS / CORS | docs/DEPLOYMENT.md |
| Day-2 operations | docs/OPERATIONS.md |
| Metrics + alerting | docs/OBSERVABILITY.md |
| Tunable knobs | docs/TUNING.md |
| Troubleshooting | docs/TROUBLESHOOTING.md |
| FAQ | docs/FAQ.md |
| Config schema | docs/CONFIG.md |
| File formats + migrations | docs/FILE_FORMATS.md |
| Deprecations | docs/DEPRECATIONS.md |
| Contributing | docs/CONTRIBUTING.md |
- Core policy engine with YAML rules (deny → require_approval → allow → default deny)
- Audit logging (JSON lines)
- Shell, filesystem, network, browser, cost scopes (string-glob matching — see Limitations)
- Approval queue with Slack/webhook/console notifications (in-memory, not persisted)
- Web dashboard (live SSE feed, stats, interactive approve/deny)
- Token-bucket rate limiting per scope per agent (in-memory)
- Per-agent policy overrides via
agents:config - Cost guardrails — per-action limits, alert thresholds, and session-level cost tracking
- Conditional rules —
require_priorandtime_windowconditions evaluated at check time - Python SDK + adapters: LangChain, CrewAI, browser-use, MCP
- TypeScript/Node.js SDK
- Full CLI: serve, validate, approve, deny, status, audit, version
- Docker support with multi-stage build
- Policy hot-reload via
--watch
- Data exfiltration detection /
datascope (PII scanning) - SQLite/PostgreSQL audit backend
- Persistent approval queue
- 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
See CONTRIBUTING.md. Priority areas: adapters for more agent frameworks, new scope types and matching strategies, dashboard UI, documentation.
Apache 2.0 — see LICENSE.
Stop hoping your agents behave. Start knowing.