AI Runtime Guard MCP Server

ai-runtime-guard

Your agent can say anything. It can only do what policy allows.

AI agents with filesystem and shell access can delete files, leak credentials, or execute destructive commands, often without the user realizing it until it is too late.

ai-runtime-guard is an MCP server that sits between your AI agent and your system, enforcing a policy layer before any file or shell action takes effect. No retraining, no prompt engineering, no changes to your agent or workflow, just install, configure once, and your agent operates within the boundaries you set.

What it does

1. Blocks dangerous operations: rm -rf, sensitive file access, privilege escalation, and more are denied before execution.
2. Gates risky commands behind human approval (optional): configurable commands require explicit operator sign-off via a web GUI before the agent can proceed.
3. Simulates blast radius: wildcard operations like rm *.tmp are evaluated against real files before running, and blocked if they exceed a safe threshold.
4. Controls network behavior: configure command-level network policy with monitor-only mode, domain allowlist/denylist, and optional unknown-domain blocking.
5. Supports multi-agent policy isolation: apply per-agent policy overrides keyed by AIRG_AGENT_ID while keeping shared runtime controls.
6. Backs up before it acts: destructive or overwrite operations create automatic backups with full restore support.
7. Provides robust logging and reporting: all allowed/blocked actions are logged to activity.log and indexed into reports.db for dashboard/log views.

Current state

1. Policy management is available in the local GUI (commands, paths, extensions, network, advanced policy).
2. Agent management is available in the GUI (Settings -> Agents), including profile-based MCP config generation.
3. Per-agent policy overrides are supported and enforced by AIRG_AGENT_ID.
4. Full runtime visibility is available through activity.log and reports/dashboard views (reports.db).
5. Stable release notes are tracked in CHANGELOG.md, with in-progress work in docs/CHANGELOG_DEV.md.

Who it is for

Developers and power users running AI agents (Claude Desktop, Cursor, Codex, or any MCP-compatible client) who want guardrails on what the agent can actually do to their system.

Known boundary

1. AIRG enforces policy only for actions that pass through AIRG MCP tools.
2. Native client tools outside MCP (for example Claude Code Glob, Read, Write, Edit, Bash) are outside AIRG enforcement and can bypass workspace/path restrictions.
3. For AIRG policy boundaries to be effective, operators must disable native shell/file tools in the client using official configuration methods.
4. Treat this as a deployment requirement, not optional hardening.
5. For Claude Code, an MCP-only sample skill is provided at docs/mcp-only.md and can be saved to <workspace>/.claude/skills/mcp-only.md.

Design scope

1. AIRG is designed to reduce accidental damage from AI agent mistakes or hallucinations.
2. AIRG is not positioned as a full malicious-actor containment system.
3. Core controls:
   • block high-risk destructive/exfiltration commands and paths
   • enforce workspace boundaries
   • gate mass/wildcard actions with simulation and budget limits
   • optionally require human approval for selected risky actions
   • automatically back up destructive/overwrite targets before applying changes
   • log allowed/blocked actions and operator decisions to an audit trail

How it works

• Python MCP server with policy-driven enforcement loaded from policy.json
• Default profile is basic protection: severe actions blocked, everything else allowed
• Advanced controls available for opt-in: simulation gating, human approval workflows, cumulative budget limits, and shell workspace containment modes (off/monitor/enforce)
• Local web GUI for policy editing, approval management, and audit log review

Requirements

Python:

1. Required: Python >=3.10 (project package metadata enforces this).
2. Recommended on macOS: Python 3.12+ (Homebrew or python.org install).
3. macOS system Python 3.9 is often too old and may fail dependency install.

How to run

Quick start (package install):

1. python3 -m venv .venv-airg && source .venv-airg/bin/activate
2. python -m pip install --upgrade pip
3. python -m pip install ai-runtime-guard
4. airg-setup (guided) or airg-setup --defaults --yes (unattended defaults)
5. airg-doctor

For source-clone setup, TestPyPI flow, and advanced options, see `docs/INSTALL.md`.

What is optional

1. Web GUI is optional, but strongly recommended for policy operations, approvals, agent profile management, and reporting.
2. GUI background service (airg-service) is option