The Missing
sudoCommand for AI Agents
Stop your AI Agent from causing unintended consequences. SudoMode is a middleware proxy that intercepts high-risk actions and enforces human approval before execution. Your agent sends intents, we hold the keys.
Hosted Cloud: Don't want to self-host? Join the SudoMode Cloud Waitlist
Demo_Sudomode.mov
Quick Install:
git clone https://github.com/numcys/sudomode.gitAI Agents can be dangerous. Prompt injection is real. You can't trust an LLM with db.drop_table() or stripe.charge(amount=999999).
Your agent has direct access to:
- Payment APIs (Stripe, PayPal)
- Databases (SQL, MongoDB)
- Cloud Services (AWS, GCP)
- Authentication Systems
One prompt injection, one bug, one hallucination can lead to catastrophic damage.
SudoMode holds the keys. Your agent only sends intents (what it wants to do). We:
- Intercept the action before execution
- Evaluate it against your policy rules
- Pause execution if high-risk
- Notify humans (Slack, Dashboard)
- Execute only after approval
The agent never touches the real API until you say so.
graph LR
A[AI Agent<br/>Client] -->|1. Intent Request| B[SudoMode<br/>Proxy]
B -->|2. Evaluate| C[Policy Engine<br/>Check Rules]
C -->|3a. Low Risk| D[ALLOW<br/>Execute]
C -->|3b. High Risk| E[REQUIRE_APPROVAL<br/>Pause]
E -->|4. Notify| F[Human<br/>Slack/Dashboard]
F -->|5. Decision| G{Approve?}
G -->|Yes| D
G -->|No| H[REJECT<br/>Block]
D -->|6. Execute| I[Real API<br/>Stripe/AWS/SQL]
H -->|6. Block| J[Agent Error]
Flow:
- Agent calls
sudo.execute("stripe.charge", {"amount": 5000}) - SudoMode evaluates against
policies.yaml - High-value charge → REQUIRE_APPROVAL
- Request appears in Dashboard + Slack notification
- Human approves/rejects
- Agent receives decision and proceeds or fails
- Intent-Based Policy - Define rules in YAML. No code changes needed.
- Long-Polling Execution - Agent pauses and waits for approval automatically.
- Real-time Dashboard - React UI for monitoring and approving requests.
- Slack Integration - Get notified instantly when approval is needed.
- Python SDK - One-line integration:
sudo.execute(resource, action, args) - Fail-Safe Default - Default deny. Only explicitly allowed actions proceed.
- Request Tracking - Full audit trail of all governance decisions.
- Zero Config - Works out of the box with sensible defaults.
git clone https://github.com/numcys/sudomode.git
# Backend Server
cd server
python3.11 -m venv venv # Python 3.11 or 3.12 recommended
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Dashboard (optional)
cd ../dashboard
npm install
# SDK (Client Library)
cd ../sdk
pip install -r requirements.txt
# Or install as package: pip install -e .Create server/policies.yaml:
rules:
# Allow read operations
- name: "allow_read"
resource: "database"
action: "read"
decision: "ALLOW"
reason: "Read operations are safe"
# Block destructive operations
- name: "deny_delete"
resource: "database"
action: "delete"
decision: "DENY"
reason: "Delete operations are forbidden"
# Require approval for high-value charges
- name: "require_approval_high_amount"
resource: "stripe.charge"
action: "charge"
condition: "args.amount > 50"
decision: "REQUIRE_APPROVAL"
reason: "High-value charge requires human approval"
# Auto-approve low-value charges
- name: "allow_low_amount"
resource: "stripe.charge"
action: "charge"
condition: "args.amount <= 50"
decision: "ALLOW"
reason: "Low-value charge auto-approved"# Terminal 1: Start backend
cd server
uvicorn app.main:app --reload
# Terminal 2: Start dashboard (optional)
cd dashboard
npm run devServer: http://localhost:8000
Dashboard: http://localhost:5173
Note: Python 3.11 or 3.12 is recommended. Python 3.14 has compatibility issues with pydantic-core.
The Client Code:
from sudomode import SudoClient
# Initialize client
sudo = SudoClient(base_url="http://localhost:8000")
try:
# Check permission before executing
result = sudo.execute(
resource="stripe.charge",
action="charge",
args={"amount": 5000}
)
if result:
# Permission granted - proceed with actual Stripe charge
print("✅ Charge approved, executing...")
# stripe.Charge.create(amount=5000, ...)
except PermissionError as e:
# Permission denied
print(f"⛔ Blocked: {e}")
except BlockingIOError as e:
# Approval required - agent pauses and waits
print(f"⏳ Waiting for approval: {e}")
# Request appears in dashboard
# Human approves/rejects
# Agent automatically resumesThat's it. Your agent is now protected.
- Policy engine with YAML configuration
- Python SDK with long-polling
- Real-time React dashboard
- Slack notifications
- Request tracking and audit trail
- RESTful API
- Docker Compose setup
- Hosted cloud version
- Webhook callbacks for approvals
- Multi-tenant support
- Advanced policy conditions (regex, time-based)
- Integration with more services (AWS SDK, etc.)
- Go/TypeScript SDKs
- Policy versioning and rollback
- AI-powered risk scoring
- Automated policy suggestions
- Integration with CI/CD pipelines
- Compliance reporting (SOC2, GDPR)
Have a feature request? Open an issue
We welcome contributions! See CONTRIBUTING.md for guidelines.
Quick contribution steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- API Documentation - Full API reference (when server is running)
- SDK Examples - More code examples including
demo_agent.pyandbank_agent.py - Policy Reference - Policy configuration guide
- Contributing Guide - How to contribute to SudoMode
Install the SDK as a package:
cd sdk
pip install -e .Or use directly:
cd sdk
pip install -r requirements.txt
python examples/demo_agent.pyThe React dashboard provides:
- Real-time Updates - Automatically polls the backend API every 2 seconds
- Dark Theme - Cyberpunk/enterprise security aesthetic
- Request Management - View, approve, or reject pending governance requests
- Risk Indicators - Visual badges showing risk levels
- Responsive Design - Works on desktop and mobile devices
API Endpoints Used:
GET /v1/requests- Fetch all requestsPOST /v1/requests/{id}/approve- Approve a requestPOST /v1/requests/{id}/reject- Reject a request
SudoMode is security-first:
- Default deny policy (fail-safe)
- Policy evaluation before execution
- Human-in-the-loop for high-risk actions
- Full audit trail
- No agent code changes required
But remember: SudoMode is a tool, not a silver bullet. Always:
- Review your policies regularly
- Monitor the dashboard for suspicious activity
- Use strong authentication for the dashboard
- Keep SudoMode server secure
- Never commit
.envfiles with real API keys
To enable Slack notifications:
- Create a Slack app at https://api.slack.com/apps
- Enable "Incoming Webhooks"
- Add webhook to your workspace
- Create
server/.env:SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
When an action requires approval, SudoMode will automatically send a formatted alert to your Slack channel.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with:
- FastAPI - Modern Python web framework
- React - UI library
- Tailwind CSS - Styling
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: Info.namansharma001@gmail.com
Made for safer AI agents
Stop trusting. Start governing.