v1.0.0 — First Public Release

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

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

What's included in v1.0.0

Core protection

• Blocks dangerous commands (rm -rf, dd, shutdown, privilege escalation, and more) before execution
• Blocks sensitive path and file extension access (.env, .ssh, /etc/passwd, .pem, .key)
• Command normalization prevents simple obfuscation bypasses (extra whitespace, case variations)
• Workspace boundary enforcement — agent actions are anchored to a configured sandbox root

Advanced policy tiers (opt-in)

• Simulation gating — wildcard operations like rm *.tmp are evaluated against real files before running and blocked if they exceed a configurable threshold
• Human approval workflow — configurable commands require explicit operator sign-off via web GUI before the agent can proceed
• Cumulative budget limits — track and bound operations, paths, and bytes across a session

Audit and recovery

• Full JSONL audit trail of every allowed and blocked action
• Automatic backups before destructive or overwrite operations
• Restore support with dry-run preview

Web GUI (optional)

• Policy editor with command tiering, path rules, and extension management
• Approval panel for reviewing and acting on pending confirmation requests
• Revert last apply and reset to defaults

Packaged CLI

• airg-init — initialize runtime paths and config
• airg-server — MCP server entrypoint
• airg-ui — start web GUI backend
• airg-doctor — verify installation and configuration

Getting started

See [INSTALL.md](INSTALL.md) for full setup instructions.

Quick start:

git clone https://github.com/jimmyracheta/ai-runtime-guard.git
cd ai-runtime-guard
python3 -m venv venv && source venv/bin/activate
pip install .
airg-init
airg-doctor

Compatibility

• Python >=3.10 required (3.12+ recommended on macOS)
• macOS: validated on Apple Silicon
• Linux: expected to work, formal validation pending (v1.1)
• MCP clients: Claude Desktop, Cursor, Codex, and any stdio MCP-compatible client

Known limitations

• Simulation blast-radius threshold defaults may need tuning for your workflow — rm *.tmp with a small file count may pass through depending on your configured threshold
• Linux not yet formally validated
• Per-command budget overrides in the GUI are metadata only — not yet enforced at runtime
• shell=True remains in command execution path; complex shell constructs are parsed heuristically

What's next (v1.1)

• Linux validation
• PyPI publishing (pip install ai-runtime-guard / uvx ai-runtime-guard)
• Simulation threshold tuning
• Install UX improvements for first-time users