# 🔥 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
```bash
# 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
```bash
# 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
```bash
# 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 `agent_bridge_secure.py`.
### 2. Enable YOLO mode in conversation
**Session A (or B) calls:**
```json
{
"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:**
```json
{
"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:
```bash
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:
```bash
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:
```json
{
"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:
```bash
# 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):**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
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:
```bash
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:
```json
{
"timeout": 300 // 5 minutes
}
```
### Docker sandbox errors
Verify Docker is running:
```bash
docker ps
```
If Docker unavailable, disable sandbox:
```json
{
"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`:
```python
SAFE_COMMANDS = {
'ls', 'cat', 'grep', 'find',
'myapp', # Your custom read-only tool
}
```
### Add custom blocked patterns
```python
BLOCKED_PATTERNS = [
r'\brm\s+-rf\s+/',
r'curl.*evil\.com', # Block specific domains
]
```
### Add restricted commands
```python
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.