mcp-multiagent-bridge/YOLO_MODE.md

🔥 YOLO Mode - Command Execution

⚠️ WARNING: This enables AI agents to execute commands on your system!

YOLO mode allows both Claude Code sessions to execute shell commands, with configurable safety levels.

Security Levels

1. Safe Mode ✅

What it allows:

• Read-only commands: ls, cat, grep, find, head, tail, wc, pwd, ps, df
• Zero risk of data modification

Use case: Code exploration, log analysis, system inspection

# Example safe commands
ls -la
cat README.md
grep "TODO" src/**/*.py
find . -name "*.js"
ps aux | grep python

2. Restricted Mode ⚠️

What it allows:

• Everything in Safe mode, plus:
• Git operations: status, log, diff, add, commit, push, pull
• Package managers: npm install, pip install, cargo build
• Test runners: pytest, npm test

What it blocks:

• Destructive git operations (reset --hard, clean -fdx)
• System modifications
• Unrestricted shell access

Use case: Development workflow with version control

# Example restricted commands
git status
git add src/
git commit -m "Update API"
npm install lodash
pip install requests
pytest tests/

3. YOLO Mode 🔥

What it allows:

• Almost everything except obvious disasters
• File creation/modification
• System commands
• Custom scripts

What it ALWAYS blocks:

• rm -rf / (recursive delete from root)
• sudo / su (privilege escalation)
• Writing to block devices (> /dev/sda)
• Piping curl/wget to bash
• Fork bombs
• eval and dangerous redirects

Use case: Experienced users in isolated environments

# Example YOLO commands
python train.py --epochs 10
docker-compose up -d
./build.sh
npm run build

Setup Instructions

1. Place YOLO module

Ensure yolo_mode.py is in the same directory as claude_bridge_secure.py.

2. Enable YOLO mode in conversation

Session A (or B) calls:

{
  "tool": "enable_yolo_mode",
  "arguments": {
    "conversation_id": "conv_...",
    "session_id": "a",
    "token": "your-token",
    "mode": "restricted",
    "workspace": "/home/user/projects/myapp",
    "timeout": 60,
    "sandbox": false
  }
}

Parameters:

• mode: "safe" | "restricted" | "yolo"
• workspace: Directory where commands execute (default: current dir)
• timeout: Max execution time in seconds (default: 30)
• sandbox: Run in Docker container (default: false, requires Docker)

3. Execute commands

Either session can execute:

{
  "tool": "execute_command",
  "arguments": {
    "conversation_id": "conv_...",
    "session_id": "a",
    "token": "your-token",
    "command": "npm test"
  }
}

Both sessions will see the result!

Safety Features

Automatic Git Snapshots

Before any command execution, YOLO mode creates a Git snapshot branch:

snapshot-20251026-143022

If something goes wrong, you can rollback:

git checkout snapshot-20251026-143022

Command Validation

All commands go through multi-layer validation:

1. Blocked patterns check - Reject known dangerous patterns
2. Mode-specific whitelist - Only allow commands for current mode
3. Argument validation - Check subcommands for restricted commands
4. Timeout enforcement - Kill long-running processes

Audit Trail

Every command execution is logged:

python3 bridge_cli.py audit conv_abc123

Shows:

• Who executed the command
• When it was executed
• Exit code and duration
• Whether it was blocked

Output Broadcasting

When Session A executes a command, Session B automatically receives:

• The command that was run
• Exit code
• stdout/stderr (truncated to 1000 chars each)
• Execution duration
• Git snapshot reference (if created)

This keeps both agents in sync about system state changes.

Docker Sandbox Mode

For maximum safety, enable Docker sandboxing:

{
  "sandbox": true
}

Commands run in isolated containers with:

• ❌ No network access (--network=none)
• 📊 Memory limit: 512MB
• ⚙️ CPU limit: 1 core
• 📁 Read-only workspace mount
• ⏱️ Timeout enforcement

Requires Docker installed and running.

Example:

# Instead of:
python my_script.py

# Runs as:
docker run --rm -i \
  --network=none \
  --memory=512m \
  --cpus=1 \
  -v "/workspace:/workspace:ro" \
  -w /workspace \
  python:3.11-slim \
  sh -c 'python my_script.py'

Usage Examples

Example 1: API Development Workflow

Session A (Backend):

# Enable YOLO mode
enable_yolo_mode(mode="restricted", workspace="/home/user/api-project")

# Create new endpoint
execute_command("cat > api/endpoints/todos.py << EOF
from fastapi import APIRouter
router = APIRouter()

@router.get('/todos')
async def get_todos():
    return {'todos': []}
EOF")

# Run tests
execute_command("pytest tests/test_todos.py -v")

# Commit if tests pass
execute_command("git add api/endpoints/todos.py")
execute_command("git commit -m 'Add todos endpoint'")

Session B (Frontend) sees all results and can:

# Check what was committed
execute_command("git log -1 --stat")

# Test the endpoint
execute_command("curl http://localhost:8000/todos")

Example 2: Debugging in Parallel

Session A:

# Enable safe mode for read-only exploration
enable_yolo_mode(mode="safe")

# Analyze logs
execute_command("grep ERROR app.log | tail -20")
execute_command("cat /var/log/app/error.log")

Session B:

# Enable restricted mode to fix the issue
enable_yolo_mode(mode="restricted")

# Apply fix
execute_command("git checkout -b fix/logging-error")
execute_command("sed -i 's/logger.error/logger.exception/g' src/logger.py")
execute_command("pytest tests/test_logger.py")

Example 3: System Reconnaissance

Both sessions in safe mode:

enable_yolo_mode(mode="safe")

# Session A: Check system resources
execute_command("df -h")
execute_command("free -m")
execute_command("ps aux --sort=-%mem | head -10")

# Session B: Check application state
execute_command("ls -lah /var/www/app")
execute_command("cat /var/www/app/.env | grep -v SECRET")
execute_command("find /var/www/app -name '*.log' -mtime -1")

Best Practices

DO ✅

1. Start with safe mode - Escalate only when needed
2. Use workspace isolation - Set workspace to project directory
3. Enable sandboxing - Use Docker when possible
4. Review commands - Check what partner executed via check_messages
5. Create snapshots manually - git stash before risky operations
6. Set appropriate timeouts - Long-running tasks need higher values
7. Use restricted mode for CI/CD - Perfect for build/test workflows

DON'T ❌

1. Don't use YOLO mode on production servers - Too risky
2. Don't disable sandboxing for untrusted code - Always sandbox third-party scripts
3. Don't execute commands you don't understand - Review partner's suggestions
4. Don't ignore blocked commands - If it's blocked, there's a reason
5. Don't run as root - Use regular user account
6. Don't trust agent judgment blindly - AI can make mistakes
7. Don't disable audit logging - You need forensics if things break

Troubleshooting

"YOLO mode not enabled for this conversation"

You need to call enable_yolo_mode first:

python3 bridge_cli.py show conv_abc123  # Verify conversation exists

Then in Claude Code session:

Use enable_yolo_mode tool with mode="safe"

"Command blocked: Blocked dangerous pattern"

The command matched a blocked pattern. Review the command for:

• sudo or su
• rm -rf /
• Piping to shell (| bash, | sh)
• Eval statements

If you believe it's a false positive, modify yolo_mode.py BLOCKED_PATTERNS.

"Command timed out after Xs"

Increase timeout when enabling YOLO mode:

{
  "timeout": 300  // 5 minutes
}

Docker sandbox errors

Verify Docker is running:

docker ps

If Docker unavailable, disable sandbox:

{
  "sandbox": false
}

Commands not in allowed list (restricted mode)

Restricted mode is strict. Either:

1. Add command to RESTRICTED_COMMANDS in yolo_mode.py
2. Switch to YOLO mode (less safe)
3. Execute manually and report results via send_to_partner

Architecture

┌─────────────────────┐
│   Session A calls   │
│  execute_command    │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  CommandValidator   │
│  - Check mode       │
│  - Check patterns   │
│  - Validate args    │
└──────────┬──────────┘
           │
           ▼ (if allowed)
┌─────────────────────┐
│  CommandExecutor    │
│  - Create snapshot  │
│  - Execute command  │
│  - Capture output   │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Broadcast result  │
│   to both sessions  │
└─────────────────────┘

Extending YOLO Mode

Add custom safe commands

Edit yolo_mode.py:

SAFE_COMMANDS = {
    'ls', 'cat', 'grep', 'find',
    'myapp',  # Your custom read-only tool
}

Add custom blocked patterns

BLOCKED_PATTERNS = [
    r'\brm\s+-rf\s+/',
    r'curl.*evil\.com',  # Block specific domains
]

Add restricted commands

RESTRICTED_COMMANDS = {
    'myapp': ['read', 'analyze', 'report'],  # Only these subcommands
}

Security Considerations

YOLO mode is designed for development environments with informed users who understand the risks.

DO NOT use in:

• Production servers
• Shared hosting environments
• Systems with sensitive data
• Untrusted networks
• Multi-tenant environments

Threat model:

• Prompt injection: Agent could be tricked into executing malicious commands
• Privilege escalation: If running as root or with sudo access
• Data exfiltration: Commands could leak secrets via network
• Resource exhaustion: Malicious loops or fork bombs
• Lateral movement: Compromised agent could attack other systems

Mitigations:

1. Run in isolated VM or container
2. Use non-privileged user account
3. Enable Docker sandboxing
4. Set aggressive timeouts
5. Monitor audit logs
6. Use network firewalls
7. Limit to development data only

License & Liability

MIT License - Use at your own risk.

We are NOT responsible for:

• Data loss
• System damage
• Security breaches
• Lost work
• Angry sysadmins

By using YOLO mode, you acknowledge:

1. You understand the risks
2. You have backups
3. You're using appropriate isolation
4. You accept full responsibility

---

Remember: With great power comes great responsibility. YOLO mode is powerful but dangerous. Use wisely.