Agent-Sudo

The Safety Interceptor for Autonomous Agents.
Adaptive High-Friction Guardrails to prevent accidental production disasters.

Prevent your agent from accidentally dropping the production database or transferring funds without authorization. Think of it as sudo for AI.

Read the Spec View on GitHub

# SUDO.md
version: "1.0"
safety_rules:
  - pattern: "DROP TABLE .*"
    risk_level: "L3"
    message: "⚠️ DATABASE DELETION DETECTED"
 
  - pattern: "transfer_.*"
    risk_level: "L4"
    auth_required: "biometric"

Why SUDO.md?

❌ Traditional HITL

"Do you agree?"

Passive approval. User clicks Yes 1000 times → muscle memory → clicks Yes on the 1001st destructive action without reading.

Human is in the loop, but the brain is not.

✅ SUDO.md Protocol

"Prove you mean it."

Active challenge-response. User must wait 5s / type confirmation / use biometric — cannot bypass with a mindless click.

Cognitive Forcing Functions that wake users up.

⚠️ The Problem: Sandboxing Is Not Enough

Sandboxes prevent malicious code escape. But AI agents are authorized users. When Codex misunderstands your intent and decides to DROP TABLE users, the sandbox won't stop it — because Codex has permission.

The Solution: Adaptive High-Friction Guardrails

⏳

L2: Temporal

5-second mandatory cooldown. Forces slow thinking.

🧠

L3: Cognitive

Type to confirm. Forces reading and understanding.

🔐

L4: Strong Auth

Passkey, TOTP, YubiKey. Out-of-band verification.

📄 SUDO.md: A Standard for AI Safety Rules

Like robots.txt tells crawlers "don't scrape here",SUDO.md tells AI agents "be careful here". Project-level, version-controlled, cross-agent compatible.

Who Should Adopt SUDO.md?

Agent developers implement SUDO.md protocol in their agents.
Project/system owners add SUDO.md files to define specific rules.

Coding Agents

Codex, Cursor, Windsurf, Devin...

Example:
Backend project has SUDO.md → Agent reads rules before executing git push, database migrations, or rm -rf

Personal AI Assistants

Moltbot, Rabbit R1, Humane AI Pin...

Example:
User asks to "sell all my TSLA stock" → Agent reads SUDO.md, requires L4 TOTP verification before executing trade

Computer Use Agents

Manus, Claude Computer Use, OpenAI Operator...

Example:
Email client has L3 rule for "delete all" → Agent requires typing confirmation before mass deletion

Workflow Agents

n8n, Zapier AI, Make...

Example:
Financial workflow defines L4 for transfers > $1000 → Agent requires TOTP verification

How It Works

1. Agent Developers: Implement SUDO.md parser + friction UI in your agent. When your agent encounters a risky action, check the project's SUDO.md and trigger appropriate friction.

2. Project Owners: Add a SUDO.md file to your repository or system. Define which operations are risky and what verification level they require.

Examples

# Sample SUDO.md file
version: "1.0"
 
safety_rules:
  # Level 2: High Impact - Requires 5s delay
  - path: "/etc/nginx/*"
    operation: "write"
    risk_level: "L2"
    delay_seconds: 5
 
  # Level 3: Destructive - Requires semantic confirm
  - command: "kubectl delete pod .*"
    risk_level: "L3"
    challenge: "semantic_echo"
 
  # Level 4: Critical - Requires Biometric
  - tool: "stripe_refund"
    risk_level: "L4"
    auth: "biometric"

Read Operations

Reading files, listing directories, fetching data from APIs.

cat config.yaml

Local File Writes

Creating or modifying files in the local development environment.

echo 'data' > output.txt

Cloud API Calls

Interacting with cloud services like AWS, GCP, or Azure.

aws s3 cp file.txt s3://bucket/

Database Mutations

UPDATE, DELETE, or DROP operations on production databases.

DELETE FROM users WHERE id = 1

View full specification on GitHub

How to use SUDO.md?

1. Add SUDO.md to your repository

Create a SUDO.md file at the root of your repository. This file defines the safety boundaries for any AI agent operating on your codebase.

2. Define your risk levels

Specify which operations require guardrails:

L0: Pass-through (read operations)
L1: Simple confirmation (local writes)
L2: Time-lock (5s delay for cloud ops)
L3: Semantic echo (type to confirm)
L4: Biometric lock (production access)

3. Add security rules

Define regex patterns for high-risk commands like `DROP TABLE`, `rm -rf`, or API calls to production endpoints. Agent-Sudo will intercept and require confirmation before execution.

4. Large project? Use nested SUDO.md files

Place additional SUDO.md files inside subdirectories. The nearest file takes precedence, allowing each microservice or package to have its own safety rules.

Protocol Specification

Agent-Sudo is an open protocol for AI-powered applications. If your app uses autonomous agents, implement the SUDO.md standard to protect your infrastructure from accidental disasters.

The SUDO.md file uses YAML format and should be placed at the repository root. Frameworks implementing this protocol MUST parse this file and enforce the defined rules.

SUDO.md Schema

version: "1.0"                    # Required: Protocol version
inherit: true                     # Optional: Inherit from parent SUDO.md (default: true)
default_level: "L1"               # Optional: Default risk level if no rule matches

security_rules:                   # Required: Array of rules
  - pattern: "regex"              # Match by regex pattern
    command: "glob"               # OR match by command glob
    tool: "tool_name"             # OR match by tool name
    path: "/path/*"               # OR match by file path

    risk_level: "L0|L1|L2|L3|L4"  # Required: Risk classification
    environment: "production"     # Optional: Only apply in this environment

    # Optional: Friction configuration
    challenge: "none|confirm|timeout|semantic_echo|strong_auth"
    delay_seconds: 5              # For L2: timeout duration
    semantic_key: "delete-prod"   # For L3: text user must type
    auth_methods: ["passkey", "totp"]  # For L4: allowed methods
    message: "Warning message"    # Display to user

    # Optional: Conditions & Fallback
    condition: "amount > 100"     # Dynamic evaluation
    fallback_level: "L3"          # If L4 fails, fall back to this level

Adding SUDO.md to Your Application?

Follow this specification to implement the interceptor pattern in your app. Questions? Open an issue on GitHub.

View Full Spec on GitHub

About Agent-Sudo

Agent-Sudo is an open protocol designed to add a safety layer between autonomous AI agents and critical infrastructure. Inspired by the Unix sudo command, it introduces “Adaptive High-Friction Guardrails” to prevent accidental production disasters.

The SUDO.md standard allows teams to define risk levels (L0-L4) for sensitive operations. When an AI agent attempts a high-risk action, Agent-Sudo intervenes with the appropriate friction — from simple confirmations to biometric authentication.

This project is open source and community-driven. We welcome contributions from developers, security researchers, and organizations building with autonomous AI agents. Contribute on GitHub →

FAQ

What problem does Agent-Sudo solve?

Alert Fatigue. Traditional Human-in-the-Loop (HITL) prompts degenerate into "Click Yes Without Looking". When users are prompted for every action, they develop muscle memory and approve without reading. The human is in the loop, but the brain is not.

Agent-Sudo solves this by requiring Proof of Intent, not just Authorization.

What is 'Proof of Intent' vs 'Authorization'?

Authorization: Passive approval. "Click OK to continue." (Easily bypassed by habit)
Proof of Intent: Active challenge-response. The user must perform a distinct, conscious action that proves they understand the consequence.

What are 'Cognitive Forcing Functions'?

Cognitive Forcing Functions are UX mechanisms designed to break users out of autopilot mode. Examples include mandatory time delays (to force reading), semantic echo (typing to confirm), and strong authentication (passkey, TOTP, etc.).

How is this different from sandboxing?

Sandboxes block malicious code. Agent-Sudo prevents 'authorized stupidity' — when an agent has legitimate access but makes a catastrophic mistake like deleting a production database due to hallucination.

What are the three types of friction?

⏳ Temporal Friction (L2): 5-second mandatory cooldown. Button disabled until timer ends. Prevents accidental clicks.
🧠 Cognitive Friction (L3): Semantic Echo. User must type the action to confirm (e.g., "delete-prod"). Forces reading and understanding.
🔐 Strong Authentication (L4): Passkey, TOTP, YubiKey, Push Notification, or SMS/Email. Frameworks choose which methods to support for critical operations.

How do I add SUDO.md to my project?

Create a SUDO.md file at the root of your repository:

version: "1.0"
security_rules:
  - pattern: "DROP TABLE"
    risk_level: "L3"
    challenge: "semantic_echo"
  - command: "rm -rf /"
    risk_level: "L4"
    auth: "biometric"

Who should adopt SUDO.md?

Two groups: (1) Agent developers — implement SUDO.md parsing and friction UI in your agent. (2) Project/system owners — add SUDO.md files to define rules for your specific project. Agents that support the protocol will enforce your rules.

How does SUDO.md relate to AGENTS.md?

They are complementary. AGENTS.md provides context and instructions for how agents should work on your project. SUDO.md defines safety boundaries and friction rules. Think of AGENTS.md as "what to do" and SUDO.md as "what to be careful about".

What if an agent doesn't support SUDO.md?

That's the agent developer's choice. Projects can only enforce rules with agents that implement the protocol. We encourage agent developers to adopt SUDO.md to build user trust.

Can I have different rules for dev vs production?

Yes. Use the environment field in your rules:

- pattern: "DROP TABLE"
  risk_level: "L4"
  environment: "production"  # Only L4 in prod

- pattern: "DROP TABLE"
  risk_level: "L1"
  environment: "development"  # L1 in dev

How do nested SUDO.md files work?

The nearest SUDO.md takes precedence. Rules from parent directories are inherited, but child directories can override them. This allows monorepos to have project-level rules while subdirectories can have stricter (or looser) rules.

Is there an emergency bypass?

The protocol does not define a global bypass. However, project owners can define an "emergency_override" rule that requires L4 authentication. This is a "break glass" scenario for critical situations.

Is Agent-Sudo open source?

Yes! Agent-Sudo is an open protocol. The specification and reference implementations are freely available on GitHub under MIT license.