Runestone Agent Gatekeeper

A policy-based gatekeeper service that sits between AI agents and real-world tools (shell, HTTP, filesystem), enforcing approvals, denials, USD budgets, and audit logging.

Who Is This For

If you're running AI agents (Claude, GPT, local LLMs, MCP servers) that execute tool calls against real systems — and you're responsible for what happens when those calls go wrong — Gatekeeper is for you. Specifically:

• You build agentic apps and your agent can run shell commands, write files, or hit external APIs.
• You've already had one "why did it do that?" moment — or you're staring down the possibility.
• You want a self-hostable, auditable, single-binary boundary between your agent and the world, without adopting an enterprise SSO stack or wiring everything through a cloud proxy.
• You need USD budgets and signed approvals as first-class primitives, not features bolted onto an observability tool.

You were probably using: nothing (and trusting the prompt), ad-hoc Python wrappers around subprocess, a cloud LLM gateway, or shell-level sudoers rules that don't understand tool semantics.

What Problem This Solves

AI agents need to execute actions in the real world: running shell commands, writing files, making HTTP requests. Without guardrails, an agent can accidentally (or adversarially) execute dangerous operations.

The Gatekeeper intercepts all tool requests and:

• Allows low-risk operations immediately
• Denies operations that match dangerous patterns
• Requires human approval for sensitive operations
• Catches sensitive-boundary crossings — Keychain, SSH keys, cloud credentials, browser profiles, package-registry tokens, env files (see Sensitive Boundary Protection)
• Rejects when a USD / token / call budget is exceeded (optional) — per actor (a rolling guardrail) or per run (scope: run, keyed on runId: caps a single agentic run at the action boundary, where recursive burn compounds)
• Optionally proxies Anthropic model calls — route inference through the gatekeeper so every /v1/messages call is audited, the API key stays centralized, and real per-token cost is metered onto the audit row and into budgets (off by default; see docs/API.md)

All decisions are logged to an append-only audit trail (jsonl or Postgres). An aggregation endpoint (/usage) exposes call counts — and real cost/token sums — by actor × tool × day. A budget endpoint (/budget) surfaces current spend vs cap per configured rule.

Sensitive Boundary Protection

Coding agents fail in subtle ways. They start with a safe task, then escalate into sensitive local operations while trying to be helpful. Gatekeeper ships a built-in rule pack that catches these crossings.

Real failure pattern: A coding agent debugging a Puppeteer / Chromium "Safe Storage" prompt on macOS first applied a normal flag-based fix (--use-mock-keychain, --password-store=basic, throwaway --user-data-dir). When the prompt persisted, the agent pivoted to inspecting the user's Keychain — and proposed deleting entries "so there's nothing to access."

# Step 2 of the agent's reasoning — Gatekeeper requires approval (high risk)
security find-generic-password -s "Chromium Safe Storage"

# Step 3 of the agent's reasoning — Gatekeeper denies outright (critical)
security delete-generic-password -s "Chromium Safe Storage"

Gatekeeper classifies these against a built-in rule pack:

| Resource class | Examples