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). JSONL receipts include a sequence, previous-entry hash, and entry hash for independent tamper/gap verification. 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.

Gatekeeper only controls actions that are actually routed through it. It does not infer coverage from installation. Verify the client's actual routing configuration before describing a runtime as protected.

Setup CLI

The gatekeeper CLI previews every client configuration change, creates timestamped backups before applying one, and can restore the last patch:

npm install --global @runestone-labs/gatekeeper
gatekeeper init --client claude-code
gatekeeper doctor
gatekeeper verify ./data/audit

Supported setup targets are claude-code, openclaw, and mcp. Fresh Claude Code patches set GATEKEEPER_FAIL_CLOSED=1. Existing fail-open hooks remain usable, but doctor reports them as a protection failure with the exact migration command.

The Cloud connection protocol is implemented for dogfooding, but the hosted team product is not generally available. The experimental connection flow uses browser device authorization and a scoped instance token stored locally with mode 0600:

gatekeeper connect
gatekeeper disconnect

Do not expect the public Cloud endpoint to be available during demand validation. Disconnect revokes Cloud access without turning off local OSS enforcement. See RUNESTONE_CLOUD.md.

Gatekeeper only controls actions that are actually routed through it. Native or bypass routes remain outside its boundary, so verify each client's real routing configuration before describing a runtime as protected.

Need a teammate to handle approvals while agents run unattended?

The local Gatekeeper server and MCP integration are free. We're testing demand for Gatekeeper Team at $49/month, for up to five members and five instances: route an agent's held action to an accountable teammate for approval or denial, with a record of what happened. This is a proposed Cloud service, not a public hosted product; no payment is collected during this test.

See the proposed workflow and share your team's needs. You can also optionally report whether you've routed a first real action through local Gatekeeper or used it again on a later day. These are manual form choices, not verified external activation. Don't send commands or raw audit logs; this test adds no automatic usage reporting to the MCP server.

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:

Each rule has an effect (allow | require_approval | deny), a stable category, a risk level, and an optional safer_alternative redirect. Rules are mirrored into riskFlags (boundary:keychain-read, category:credential_store_access, risk:high) so existing audit consumers work unchanged.

Defaults always load — no opt-in required. Override or extend them under sensitive_boundaries: in your policy.yaml; the full reference dump lives at policies/sensitive-boundaries.yaml. A demo fixture for the Puppeteer → Keychain escalation is at examples/sensitive-boundaries/keychain-scope-creep.json.

Use it from Claude Code

@runestone-labs/gatekeeper-claude-code is a Claude Code PreToolUse hook that routes Bash / Write / Edit / WebFetch through Gatekeeper before Claude Code executes them. Install once globally, drop the settings.example.json snippet into ~/.claude/settings.json, and every gated tool call gets evaluated against the boundary pack:

npm install -g @runestone-labs/gatekeeper-claude-code

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|WebFetch",
        "hooks": [{ "type": "command", "command": "gatekeeper-claude-code-hook" }]
      }
    ]
  }
}

The legacy hook remains fail-open by default if the Gatekeeper server is down. The setup CLI sets GATEKEEPER_FAIL_CLOSED=1 for new managed installations and reports existing configurations that do not. Approval-required Bash, Write, and WebFetch calls are registered as exact idempotent holds and executed locally once after approval. Edit is policy-checked but is never reduced to a destructive whole-file write. See integrations/claude-code/README.md for the full configuration reference.

Use it from any MCP client

@runestone-labs/gatekeeper-mcp is a stdio MCP server that lets any MCP client (Claude Desktop, Claude Code, Cursor, …) run real tool calls — shell_exec, files_write, http_request, a generic gatekeeper_call, plus gatekeeper_health — but only by routing every call through Gatekeeper. Identity, role, and origin are pinned server-side (the model can't escalate via tool arguments), and it fails closed: a deny, a pending approval, or any malformed Gatekeeper response surfaces as an error, never as a successful result.

Add it to your MCP client config: