Squidbrake

Change control for AI agents. Every action an agent takes (running a command, editing a file, sending an email, issuing a refund, changing a database) goes through Squidbrake first. It is checked against your team's rules, held for someone else to approve when it's risky, recorded in a tamper-evident audit trail your auditor can check, and can be stopped instantly. One policy for Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot, Antigravity and your MCP tools.

Free and open source (Apache 2.0). Runs on your laptop or your own server; your data never leaves it.

• Rules, not vibes: rules.yaml says what runs by itself, what's blocked, and what waits for a person. No LLM in the decision path.
• Human approval: risky actions wait in the dashboard, on your phone (one-tap links, push via ntfy) or in Slack. The approver sees what led to it, e.g. the email the agent just read.
• Reads what a command really does: ls && rm -rf ~/, bash -c "...", rmdir /s /q d:\ or curl ... | sh are split and read before they run. Wiping a disk or home folder is blocked; git push --force, terraform destroy, kubectl delete or cloud deletes wait for a person; commands that only look (ls, git status) run without asking.
• Catches prompt injection without a model: if an agent sends data to an address that only a web page, email or issue mentioned (not you, not your own systems), it's held and the approver is told where the address came from.
• Judges by history: blocks a retry of something a person rejected, catches look-alike domains (acrne-corp.com pretending to be acme.com), flags duplicate refunds, and lets you write sequence rules ("deleting a database right after its backups were turned off") that say which earlier step caused them.
• Works with real agents: squidbrake connect all connects Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot and Antigravity (their commands, reads and edits, via hooks) and the MCP servers they already use; any MCP app (Stripe, GitHub, Slack, databases, internal tools) can be wrapped too.
• For teams: one gateway for everyone's laptops (connect all --url https://gateway.yourcompany.com --key gw_..., one agent key per person, made in Team with "Works for" set), roles (only finance approves wires), second-person approval (nobody approves what their own agent asked for), an emergency stop (all agents, one agent, or one conversation, which also ends Claude Code's turn), reports, CSV export, and evidence anyone can verify offline (python verify.py).
• Shows what it will change, and keeps an undo: before a risky command, the approver sees it measured on the developer's machine ("removes 3 commits from origin/main: fix login, ...", "deletes 1,204 files (56 MB) in data", "deletes 4,312 rows of 10,240 in orders", "destroys 12 resources in workspace prod, including 1 that holds data: aws_db_instance.main", "deletes the bucket and all 8,200 objects (14.0 GB)"). Database rows are counted with the same WHERE in a read-only session with a timeout (psql, mysql, sqlite3); terraform is read from its state or a plan without refresh or lock; AWS and Kubernetes use list and describe calls with the command's own credentials. Right before an approved delete, git reset --hard or git clean runs, Squidbrake keeps a copy; squidbrake undo lists them and squidbrake undo ID puts one back.
• Can't be switched off: squidbrake lockdown --url https://gateway.yourcompany.com writes the managed-settings files IT pushes to every machine (Claude Code, Codex, Gemini CLI, Cursor), so each agent must run Squidbrake's hook and --dangerously-skip-permissions / --yolo are turned off. One policy, every agent.
• Ready for your auditor: squidbrake evidence (or Reports → Evidence pack) writes one printable page: the controls in place, what was blocked, held and approved and by whom, whether the audit trail is intact, and which SOC 2, ISO/IEC 42001, EU AI Act, CERT-In and RBI requirements those records speak to.
• Fails closed: if Squidbrake is down, guarded tools don't run.

See SHOWCASE.md for a 5-minute demo with a sandbox company, and incidents/ for 9 real AI-agent incidents replayed against the shipped rules (Replit, the Railway volume deletion, GitHub MCP, Supabase MCP, Postmark MCP, Claude Code and Antigravity deletes...): 11 of 12 harmful actions stopped, checked in CI. The same steps through two other guards (destructive_command_guard, Microsoft's Agent Governance Toolkit), plus everyday coding work: bench/compare/.

An agent read an "urgent CEO" email from acrne-corp.com and tried to wire $24,800. Blocked, with the story of what led to it.

Approve or reject from your phone with one tap.

See it live, nothing to install

Click the button and the live demo starts in your browser (free with a GitHub account): a sandbox company's AI support agent works its inbox while you watch. A scam wire is blocked, refunds wait for a person, and a demo manager approves or rejects them. If the editor asks whether to allow tasks that run automatically, click Allow: that's the demo starting. On your own machine: pip install -r requirements.txt then python demo/live_demo.py.

Try it in 30 seconds

pipx install squidbrake           # or: pip install squidbrake
squidbrake connect all            # every AI agent on this computer now goes through it
squidbrake                        # start it: opens the dashboard

connect all finds the agents you have (Claude Code, Cursor, Codex, Gemini CLI, VS Code Copilot, Antigravity) and the MCP servers they already use, and routes them all through Squidbrake. It prints your dashboard key the first time, backs up every config it changes, and squidbrake connect all --remove undoes it. Restart the agents, then ask one to run rm -rf ~/ and watch it get blocked. squidbrake connect status shows which agents are covered, and catches the one step people miss (Codex runs a new hook only after you approve it in /hooks).

Your rules, keys and data live in ~/.squidbrake; edit ~/.squidbrake/rules.yaml and changes apply at once.

Only Claude Code? It's also a plugin, installed from inside Claude Code (see plugin/): /plugin marketplace add batrapulkit/squidbrake, then /plugin install squidbrake@squidbrake.

From a clone instead: git clone https://github.com/batrapulkit/squidbrake && cd squidbrake, then ./start.sh (Windows: start.bat) and ./connect.sh claude-code (Windows: connect.bat claude-code).

Or with Docker: docker run -d -p 8080:8080 -v squidbrake-data:/app/data --name squidbrake ghcr.io/batrapulkit/squidbrake (keys: docker logs squidbrake).

1. Start it

The first start installs everything, prints an admin key (for the dashboard) and an agent key (shown once, so save them), and opens http://localhost:8080/dashboard. No configuration needed; every setting in .env.example is optional.

Keys: python server.py add-key NAME [--approver], python server.py remove-key NAME, python server.py keys. Changes apply immediately, no restart needed. (Inside Docker, prefix with docker compose exec gateway.)

2. Connect real agents

With the gateway running, one command per agent (installed with pip, type squidbrake connect ... instead; from a clone, use the .venv Python that start.bat / start.sh created):

.venv/Scripts/python connect.py all                  # every agent at once (Windows; macOS/Linux: .venv/bin/python)
.venv/Scripts/python connect.py claude-code          # or one at a time
.venv/Scripts/python connect.py mcp --name antigravity   # also: claude-desktop, cursor

• Claude Code: a hook sends every tool call (Bash, PowerShell, Edit, Write, Read, WebFetch, MCP tools) through the gateway before it runs. Blocked calls are refused with the reason, and calls held for approval wait until you decide in the dashboard. It also adds the database tools below. Add --project DIR to limit it to one project; --remove undoes it. If the gateway is down, Claude Code's tool calls are blocked (fail closed) and it says why.
• Antigravity, Claude Desktop, Cursor, any MCP client: prints the config block to paste in. The agent gets list_tables, describe_table, query and execute tools on a SQLite database (data/shop.db, created with sample customers / products / orders; set DB_PATH to use your own). Reads run immediately, UPDATE/DELETE/INSERT/ALTER wait for your approval, and DROP/TRUNCATE are blocked.

Wrapping a GitHub, Stripe or Slack MCP server? Start with the commented example policies in examples/rules/ and adjust their tool-name patterns to the server's tool list.

Things to ask the agent, then watch the dashboard:

• "Show me the top 5 customers by revenue" (runs)
• "Give every customer on the team plan a 15% discount" (waits for you to approve)
• "Delete all failed orders" (approve or reject it; a rejection note is passed back to the agent)
• "Drop the orders table" (blocked)
• In Claude Code: "commit and push this" (the git push waits for approval)

3. Show it to someone

• Right now, from your PC: cloudflared tunnel --url http://localhost:8080 prints a public https://….trycloudflare.com link. Give viewers their own key: python server.py add-key guest. Afterwards, press Ctrl+C and run python server.py remove-key guest.
• Permanently: ./install.sh gateway.yourdomain.com on a small cloud server.

4. Other computers (a friend, a teammate, a server)

Make a clean copy (no keys, no history): python pack.py -> dist/squidbrake.zip.

• Their own gateway: unzip, double-click start.bat (Windows) or run ./start.sh. It makes its own keys.
• Their agents on YOUR gateway: in your dashboard's Team tab add them (a person, to watch/approve) and add their agent (type AI agent); send them that agent key. They unzip and run, for example: connect.bat wrap --sandbox --agent claude-code --url https://your-gateway --key gw_... (or connect.bat claude-code --url ... --key ... to route every Claude Code action through your gateway).
• A cloud server, 24/7: unzip there and run bash install.sh (HTTPS included, no domain needed).

Other ways to send calls through it

Any MCP server - put Squidbrake in front of it, in any MCP client. The agent sees the app's normal tools, and each call is checked first (with GATEWAY_URL and GATEWAY_API_KEY set in the client's MCP config):

squidbrake proxy --app linear --url https://mcp.linear.app/mcp          # a remote MCP server
squidbrake proxy --app stripe -- npx -y @stripe/mcp --tools=all          # one started by a command

squidbrake connect guard does this for the servers your agents already use.

Python - wrap your tools:

from client import Gateway, Denied
gw = Gateway("https://gateway.example.com", api_key="...", source="my-agent", session_id=run_id)

@gw.guard(name="shell.exec")
def shell_exec(command: str): ...

Any language - two HTTP calls (header X-Gateway-Key: <secret>):

POST /v1/events               {"name": "shell.exec", "input": {...}, "source": "...", "session_id": "..."}
  -> {"event_id": "...", "decision": "allow" | "deny", "reason": "...", "rule_id": ...}
POST /v1/events/{id}/result   {"output": ..., "error": null, "duration_ms": 12}

Record an action that already happened in one call by including output/error in the first POST.

HTTP proxy - no code changes: define upstreams in rules.yaml, then point the client at http://gateway:8080/proxy/<upstream>/.... Optional headers: X-Gateway-Source, X-Gateway-Session. Denied requests get 403; every response carries X-Gateway-Event-Id.

Try it on real work first: shadow mode

Set mode: shadow in rules.yaml (or shadow_agents: ["new-bot*"] for some agents) and Squidbrake blocks and holds nothing: it records what it would have done. Reports then shows would block and would hold counts, and each event is tagged, so a team can see a week of real decisions before switching mode: enforce on. Stops and catastrophic commands (rm -rf /, wiping a drive) are enforced even in shadow mode.

Command checks

Shell tools (Claude Code's Bash and PowerShell, or any tool matching command_checks.tools) are read by commands.py before the rules decide: the line is split on &&, ;, | (outside quotes), and sudo, xargs, bash -c, powershell -Command and $(...) are looked inside. Nothing is ever run or expanded.

Command checks apply even when a rule allows the tool, and read_only: allow only relaxes the default (never a rule or a warning). Configure them under command_checks: in rules.yaml.

Prompt injection, caught without a model

The attacks that actually happened to agents (a GitHub issue, a support ticket or a web page telling the agent to send data somewhere) share one shape: the destination comes from content someone else wrote. Squidbrake records what you ask (Claude Code prompts, via the hook) and which tools bring in outside content (WebFetch, inboxes, issues, tickets...). When an action sends something to an email address, URL, bank account or repo that appears in that outside content but not in what you asked or in your own systems' results, it's held with the reason:

This sends to keys@evil.io (to), which appears in WebFetch (2 minutes ago) but not in anything you asked or in your own systems. Content from outside can carry hidden instructions (prompt injection).

Uploads from the shell count too (curl -d @.env https://..., scp, git push). Anything sent out after outside content was read gets a warning for the approver. Configure it under taint_checks: in rules.yaml.

Sequence rules

Some actions are only dangerous because of what came before them. sequences: in rules.yaml judges an action by the steps before it and names the step that caused the decision:

sequences:
  - id: destroy-after-recovery-removed      # turn off backups, then delete the database
    action: review
    reason: Destroying data right after its backups or deletion protection were turned off
    match: { input_regex: 'delete[-_ ]?db[-_ ]?instance|terraform\s+destroy|drop\s+(table|database)' }
    after:
      match: { input_regex: 'backup[-_ ]?retention[-_ ]?period\W{0,4}0|deletion[-_ ]?protection\W{0,4}false' }
      within_hours: 24
  - id: runaway-refunds                     # an agent stuck in a loop
    action: deny
    reason: Too many refunds in a short time
    match: { name: ["*refund*"] }
    count: { more_than: 10, within_hours: 1, scope: agent }

The approver then sees, for example: Destroying data right after its backups were turned off. Because earlier: Bash aws rds modify-db-instance --backup-retention-period 0 (12 minutes ago). after: looks at steps in the same conversation that went ahead (same_target: true = on the same charge, file or account); count: counts earlier matching actions per session, agent or all. Actions: deny, review or warn.

Human approval

Rules with action: review hold the call until a person approves or rejects it:

- id: approve-payments
  action: review
  reason: Money movement needs a human
  timeout_seconds: 600     # default APPROVAL_TIMEOUT (300)
  on_timeout: deny         # or allow
  approvers: [alice, bob]  # optional; default = any approver key
  match: { name: "payments.*" }

• The first POST /v1/events returns "decision": "review". The Python client handles this for you: check() and @gw.guard block until the call is decided, then run the tool or raise Denied. Other clients long-poll GET /v1/events/{id}/decision?wait=25 until decision is allow or deny.
• To decide, use the Needs approval queue at the top of the dashboard, or call POST /v1/events/{id}/approve / .../reject with an optional {"note": "..."}.
• Only approver keys (python server.py add-key NAME --approver, and the rule's approvers if set) can decide, and a key can never approve its own request. So give people their own keys, separate from the agents' keys.
• If nobody decides before the deadline, on_timeout applies and decided_by is recorded as timeout.
• Every decision is stored on the event with who decided, when, and their note.
• Set APPROVAL_WEBHOOK_URL (plus PUBLIC_URL) to get a Slack- or Discord-formatted message with a link to the event whenever something needs approval.
• Through the HTTP proxy, a held request stays open until it's decided, so the caller's HTTP timeout must be longer than the rule's timeout_seconds.

Dashboard

Open http://<host>:8080/dashboard and paste your admin key (or any key made with add-key). It is stored only in that browser. The page shows:

• totals per status (click a tile to filter), a calls-per-hour/day chart (hover for counts, click a bar to list just that hour, "View as table" for exact numbers), and the top tools
• the event list, updated every 5 s while "Live" is on. Filter by time range, search, status, kind, source or session. Click a source or session to filter by it. "Load older" pages back.
• the full record for any event: input, output, error, metadata, the rule that blocked it, timings
• filters are kept in the URL, so a view like /dashboard?status=denied&range=7d can be bookmarked or shared

FAQ

How is Squidbrake different from Claude Code's built-in allow/ask permissions?

Claude Code's built-in permissions control actions for an individual agent. Squidbrake provides centralized rules for a whole team, with approvals from your phone or Slack, history checks, an audit trail, and support across multiple agents.

What happens if Squidbrake is down?

Squidbrake fails closed. Guarded tool calls are blocked if the gateway is unreachable, rather than being allowed through.

Does my data leave my machine?

No. Squidbrake is self-hosted and runs on your laptop or your own server. Your data stays in your environment.

Does Squidbrake use an LLM to make decisions?

No. Squidbrake uses deterministic rules and checks. There is no LLM in the decision path.

Can an agent get around Squidbrake?

Squidbrake is built for the common case: a cooperative agent that makes a mistake or follows instructions it found in an email, a web page or an issue. It is not a sandbox against an agent that is deliberately trying to escape. Here's what that means in practice:

• Caught: what the agent does through a connected tool. That includes shell commands read before they run (ls && rm -rf ~/, bash -c "...", curl ... | sh), MCP calls, edits to its own settings, hooks and MCP servers or to Squidbrake's rules (held for a person), and chains of steps such as backups switched off and then a delete.
• Not caught:
  • Code the agent writes and then runs. python cleanup.py is read as one command, and what the script does inside isn't seen.
  • Tools that aren't connected (squidbrake connect status shows which are).
  • Damage done inside an MCP server after the call it checks: see the postmark-mcp row in incidents/.
• For a hostile agent, add a sandbox (a container or a VM, with no credentials it doesn't need) underneath. Squidbrake then decides what is allowed, and the sandbox makes sure nothing goes around it.

See SECURITY.md for the full security model.

Querying

Evidence anyone can check

Every decision is written to a hash-chained audit trail together with the fingerprint of the rules.yaml version that made it, and each version's text is kept. Reports > Tamper check > Download evidence (or GET /v1/audit/export.json) gives one file that anyone can check on their own machine, without trusting the server:

python verify.py squidbrake-evidence-20261001-0930.json

It confirms the chain is unbroken, that every recorded action still matches the fingerprint taken when it happened (so rows edited in the database are caught, not just edits to the log), and that every decision's rules version is in the file. verify.py needs only the Python standard library. The dashboard's tamper check runs the same checks live. Add --json for one machine-readable object (ok, the number of records checked, and a list of problems with the record each one was found in) for CI; the exit code stays 0/1 either way.

Behaviour notes

• Fail closed: the Python client refuses to run a tool if the gateway is unreachable (fail_open=True to change that).
• Rules hot-reload on file save; a broken edit is logged and the last good rules stay active.
• Audit records are write-once: a result can be posted once, never for a denied call, and never while the call is still awaiting approval. Each approval can be decided only once. If two approvers click at the same moment, only the first decision counts.
• Upgrades: new columns are added to an existing database automatically at startup.
• Redaction: keys like password, token, api_key, authorization, cookie and values like Bearer ..., sk-..., ghp_..., AWS, Slack, Stripe, Google and npm keys, JWTs, private keys and the password in a URL (postgres://user:...@host) are stored as [REDACTED]. Rules still see the raw input.
• Payloads over MAX_PAYLOAD_CHARS are truncated in storage. Proxy responses are buffered (no streaming/SSE).
• SQLite (WAL) is fine for one machine. For several gateway replicas, set DATABASE_URL to Postgres.

Tests

pip install pytest && pytest -q
python tests/e2e_business_scenario.py

Usage sharing (opt-in)

Squidbrake sends nothing anywhere by default. There are two ways to share, and both show exactly what will be sent and ask first (the default answer is no):

• squidbrake connect all, run in a terminal, asks once at the end whether to share counts with the Squidbrake team. It never asks again after a no, and never asks with --yes or in scripts.
• A pilot joins with the code they were given: squidbrake pilot join CODE --server URL.

What is shared is usage counts: actions allowed, held, approved and blocked per day, and which agents and rules. Never commands, code, prompts or keys. squidbrake pilot leave stops it. Details: pilot.py and insights/.

Roadmap

• Reach checks for AWS (#18, design): before an IAM change runs, work out what the agent will be able to reach afterwards, and hold it if that crosses a line (admin roles, production, secrets). Stops an agent from giving itself admin in steps that each look harmless.
• An optional risk model that can only escalate (#16): a second opinion that can hold an action, never allow one.
• More agents connected in one command: Cursor install (#2), more rule packs like the GitHub, Stripe and Slack ones.

Tell us what you need most: 👍 or comment on the issues.

Contributing, security, license

• CONTRIBUTING.md: a 10-minute setup, and good first issues that name the file and function to change. Comment on one to claim it. Hacktoberfest pull requests are welcome.
• SECURITY.md: report vulnerabilities privately
• Licensed under the Apache License 2.0