The ai-runtime-guard server is a policy-enforcing intermediary for AI agents, providing controlled file operations and command execution with safety checks, logging, backups, and approval gates.
Execute commands (execute_command): Run shell commands subject to full policy evaluation (workspace containment, command-tier rules, Script Sentinel checks) and human approval gates; destructive patterns are blocked or require explicit approval.
Read files (read_file): Read text files from within allowed workspace paths.
Write files (write_file): Create or overwrite files with policy enforcement, automatic logging, and backup creation.
Edit files (edit_file): Apply targeted text replacements with pre-edit backup support.
Delete files (delete_file): Delete after policy checks, with optional pre-delete backup for safety.
List directories (list_directory): List directory contents with metadata, respecting path and depth policies.
Restore backups (restore_backup): Restore files from AIRG backup manifests, supporting dry-run planning and token-gated apply.
Inspect server info (server_info): Retrieve runtime identity details, build ID, workspace root, and base directory.
The server enforces workspace/path boundaries, supports per-agent policy overlays (AIRG_AGENT_ID), and includes security hardening via Script Sentinel and universal agent posture enforcement. All allowed, blocked, and pending actions are logged for auditing, and an optional web GUI enables policy editing, approvals, and agent management.
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 until it is too late.
Runtime Guard sits between your AI agent and your system, enforcing policy on every file and shell action before it executes. Install once, configure your rules, and your agent operates within the boundaries you set. Works with Claude Code, Claude Desktop, Cursor, Codex, and any MCP-compatible client. No retraining, no prompt engineering, no external account required.
agent -> execute_command("rm -rf /tmp/build")
✗ BLOCKED destructive command pattern: rm -rf
matched_rule: destructive_command | decision: blocked
agent -> execute_command("git push --force")
⏸ APPROVAL REQUIRED awaiting operator
token: a4f2b9 | expires: 10min | check GUI to approve
agent -> write_file("README.md", ...)
✓ ALLOWED backup created before write
backup_location: ~/.local/state/airg/backups/2026-03-18Related MCP server: Stage0 Authorization MCP Server
pipx install ai-runtime-guard
pipx ensurepath # if airg* commands are not found
# open a new terminal
airg-setup
airg-doctorAfter setup, open http://127.0.0.1:5001 and add your first agent from Settings -> Agents.
Alternative quick start (venv):
python3 -m venv .venv-airg && source .venv-airg/bin/activate
python -m pip install --upgrade pip
python -m pip install ai-runtime-guard
airg-setup (guided, recommended: select/create workspace during setup; includes telemetry opt-in prompt, default Yes)
airg-doctor
Open GUI Settings -> Agents, add agents manually, and apply MCP config/hardening from there.
Source-clone path:
git clone --branch main https://github.com/runtimeguard/runtime-guard.git
cd runtime-guard
python3 -m venv .venv-airg && source .venv-airg/bin/activate
python -m pip install --upgrade pip
python -m pip install .
airg-setup
airg-doctor
Unattended automation-only setup (CI/non-interactive):
airg-setup --defaults --yes --workspace /absolute/path/to/workspace
See docs/INSTALL.md for the full install reference.
Prevention
Blocks destructive commands (rm -rf, privilege escalation, sensitive file access) before they run
Auto-backs up any file before destructive or overwrite operations
Control
Gates risky commands behind explicit human approval via local GUI or API
Enforces workspace and path boundaries keyed to AIRG_WORKSPACE
Supports per-agent policy overlays keyed to AIRG_AGENT_ID
Configurable network policy with allowlists, denylists, and monitor/enforce modes
Visibility
Logs every allowed, blocked, and pending action to activity.log
Indexes events into reports.db for a dashboard view of agent behavior
Hardening
Script Sentinel: detects attempts to launder blocked commands through scripts
Universal agent hardening: GUI-driven posture enforcement including hooks, sandboxing, and native tool restrictions (support varies by client)
Runtime Guard is built as an MCP server because MCP provides the interception point you need. When your agent issues a tool call, Runtime Guard evaluates it against policy before execution. For clients that support pre-tool hooks (like Claude Code), AIRG can also deny the agent's native file and shell tools, forcing risky operations through the policy layer.
This approach is the closest to kernel-level enforcement without requiring system privileges or modifying your agent, and it works across any MCP-compatible client without per-agent engineering.
Developers and operators running AI agents who want deterministic guardrails on what an agent can actually do to their system, without giving up agent autonomy or rewriting their workflow.
Platform | Clients |
macOS | Claude Code, Claude Desktop, Cursor, Codex |
Linux | Claude Code, Claude Desktop, Cursor, Codex |
Enforcement depth varies by client. MCP policy enforcement is universal; hook-based native tool restriction and sandboxing depend on what each client exposes.
For Codex, AIRG supports both user-scope (~/.codex/) and project-scope (<workspace>/.codex/) artifacts. Project-scope enforcement requires the workspace to be trusted in the user-layer ~/.codex/config.toml before Codex will load the project .codex/ files. AIRG writes Codex tool approval stanzas only in the project-scoped .codex/config.toml.
What AIRG is designed for: reducing accidental damage from agent mistakes, hallucinated commands, and policy-evasion patterns.
What AIRG is not: a full malicious-actor containment platform.
Known enforcement boundary:
AIRG enforces policy only on actions routed through AIRG MCP tools
Native client tools outside MCP (e.g. Claude Code's built-in Bash, Glob, Read, Write, Edit) bypass AIRG unless the client is configured to restrict them
For strict enforcement, use Settings -> Agents in the GUI to apply hook-based native tool restrictions where supported
AIRG_WORKSPACEThe default project root for guarded agent operations. execute_command runs from this directory, file tools evaluate path policy relative to this root, and traversal outside the root is blocked. Multiple workspaces are supported. Each agent profile should set workspace explicitly in its MCP config.
AIRG_AGENT_IDThe runtime identity key used for activity and report attribution, per-agent policy override resolution, and posture state in Settings -> Agents.
AIRG includes a local web control plane at http://127.0.0.1:5001 for policy editing, approvals, agent profile management, reports, and telemetry control.
Service commands:
airg-service install --workspace /absolute/path/to/airg-workspace
airg-service start | status | stop | restart | uninstallAIRG supports optional anonymous telemetry to help prioritize improvements. It is opt-in during setup (default: Yes) and can be toggled any time from Policy -> Advanced -> Anonymous telemetry.
No command text, file contents, paths, prompts, usernames, or machine identifiers are collected
One aggregate payload per UTC day
Payload preview available in the GUI before enabling
Full details in docs/telemetry.md
Delete a single file after policy checks and optional pre-delete backup.
Inputs: path (required), ctx. Returns: result
Apply targeted text replacements in an existing file with backups.
Inputs: path (required), old_text, new_text, replace_all, +2 more. Returns: result
Execute a shell command after full AIRG policy and approval checks.
The command is evaluated against network/workspace containment, command-tier policy, Script Sentinel continuity checks, and optional confirmation gates before execution.
Inputs: command (required), retry_count, ctx. Returns: result
List directory entries with metadata, honoring path and depth policy.
Inputs: path (required), ctx. Returns: result
Read a text file from the workspace after path-policy enforcement.
Inputs: path (required), ctx. Returns: result
Restore files from a recorded AIRG backup manifest.
Supports dry-run planning and token-gated apply mode when restore confirmation is required by policy.
Inputs: backup_location (required), dry_run, restore_token, ctx. Returns: result
Return runtime identity details for this AIRG server instance.
Includes build id, active workspace root, and resolved base directory.
Inputs: ctx. Returns: result
Write full file content with policy checks, logging, and backup support.
Inputs: path (required), content (required), ctx. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool targets a distinct operation: file read/write/edit/delete, command execution, directory listing, backup restore, and server info. No two tools have overlapping purposes.
All tool names follow a consistent snake_case verb_noun pattern (e.g., delete_file, execute_command, server_info). No mixing of conventions.
8 tools is well-scoped for a runtime guard. Each tool earns its place by covering essential file, command, backup, and info operations without bloat.
Covers core CRUD-like operations for files, plus command execution and backup. Minor gaps like missing move/copy or directory creation tools, but agents can work around with existing tools.
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
MCP enforcement layer that intercepts AI agent actions and blocks rule violations before execution.
Real-time MCP & A2A prompt-injection, jailbreak, and tool-schema poisoning firewall for AI agents.
MCP gateway with runtime security policy, tool-call-level control, and audit of agent actions.
