Suvra

Quickstart

Suvra is a zero-config agent action firewall. No policy file, no Docker, no bootstrap tokens — install it, run the demo, then wire it into your agent runtime.

1. Install

pip install suvra

Requires Python 3.10, 3.11, or 3.12. Verify the install:

python -c "import suvra; print(suvra.__version__)"

Expected output: a version string like 26.5.0.

2. Watch it block catastrophic actions

suvra demo

This runs a scripted sequence through the built-in classifier — no policy file, no network calls:

Suvra — agent action firewall
No policy file. No setup. Just the built-in guardrail classifier.

[1/4] rm -rf / --no-preserve-root         -> BLOCKED         (catastrophic: destructive shell)
[2/4] DROP TABLE customers;               -> BLOCKED         (catastrophic: destructive SQL)
[3/4] rm -rf build/                       -> NEEDS APPROVAL  (risky: destructive shell)
[4/4] fs.write_file workspace/notes.txt   -> ALLOWED         (safe)

Every decision is deterministic — no LLM, no network call, sub-millisecond. Core Concepts explains the three danger classes and why the classifier is a floor under any policy you add later.

3. Protect your agent runtime

For Claude Code, run this in your project directory:

suvra init claude-code

This writes a PreToolUse hook into .claude/settings.json, so every tool call Claude Code makes is checked by Suvra before it runs. Re-run claude in the directory and ask it to do something destructive in a scratch repo — the tool call comes back denied with a reason instead of executing.

The other runtimes are one command each:

suvra init codex      # OpenAI Codex  (.codex/hooks.json)
suvra init hermes     # Hermes        (~/.hermes/config.yaml)

OpenClaw and the Claude Agent SDK integrate through Python instead of an init command. Agent Runtimes covers all of them — what each command writes, runtime-specific behavior, and how to protect a runtime Suvra has no init command for.

4. Wrap any MCP server

suvra mcp wrap -- npx -y @modelcontextprotocol/server-filesystem .

suvra mcp wrap launches the command as a subprocess, speaks stdio JSON-RPC to it like a normal MCP client, and gates every tools/call request through the firewall before it reaches the wrapped server. Point your MCP client (Claude Desktop, Claude Code, etc.) at the suvra mcp wrap command instead of the raw server command.

5. See every decision in a dashboard

suvra serve

Open http://127.0.0.1:8000/dashboard for every decision Suvra has made, pending approvals, and the active policy — all backed by a local SQLite database. See the Dashboard Overview.

Troubleshooting

"Suvra requires Python 3.10 or higher" — check python --version; on an older interpreter, install a newer Python (e.g. via pyenv) and re-create your virtualenv.

Where does the audit database live? — a local SQLite file at data/audit.db by default. Override with SUVRA_DB_PATH=/path/to/audit.db, or point SUVRA_DATABASE_URL at Postgres for shared use (Deployment has the full environment variable reference).

Nothing is being blocked — run suvra demo to confirm the classifier works independent of your integration wiring, then check that your hook or SDK call is actually in the tool-call path for your runtime.

MCP wrap doesn't intercept anything — make sure your MCP client invokes suvra mcp wrap -- <original command> rather than the original command directly; Suvra can only gate traffic that passes through it.

Next steps

  • Human approvals & Slack — pause risky actions for a human and get notified in Slack
  • Policy Model — write your first policy file and say exactly what your agent may do
  • What is Suvra? — the action-layer positioning and how the free local firewall grows into a shared control plane