Human-in-the-loop execution for LLM agents.
Shannot lets you see what AI agents want to do before they do it. Scripts run in a supervised environment that captures all commands and file writes. You review in a TUI, approve what's safe, and only then do changes apply.
flowchart LR
A[🤖 Agent writes script] --> B[shannot run]
B --> C[📋 Intent captured]
C --> D[shannot approve]
D --> E[👤 Human reviews]
E -->|✓| F[✅ Executes]
E -->|✗| G[🚫 Blocked]
# Install
pip install shannot
# Run a script (captures what it wants to do)
shannot run fix-nginx.py
# Review and approve
shannot approveThat's it. Two commands.
Supervised Execution
- All system calls intercepted via PyPy sandbox
- Commands captured during dry-run, executed only after approval
- File writes captured with full content, committed only after approval
- Diff preview for every file modification
Remote Execution
- Run scripts on remote Linux servers via SSH
- Zero dependencies on target — binary deployment
- Same approval workflow, regardless of where code runs
shannot run fix-nginx.py --target admin@prod.example.com
shannot approveZero Dependencies
- Pure Python stdlib — nothing to install beyond Python 3.11+
- PyPy sandbox runtime auto-downloads on first use
- Works out of the box on any Linux system
Danger Classification
- Commands color-coded by risk in TUI
- Auto-approve safe operations (ls, cat, df)
- Always-deny destructive patterns (rm -rf /)
- Everything else requires human review
Checkpoint and Rollback
- Automatic checkpoint before execution
- Restore files to pre-execution state with
shannot rollback - Conflict detection prevents accidental overwrites
# Recommended
pip install shannot
# Or with uv
uv tool install shannot
# Or with pipx
pipx install shannotRequirements:
- Python 3.11+ (host system)
- Linux (sandbox execution) or macOS (remote execution only)
Note: Scripts run in Python 3.6 (the PyPy sandbox version).
# Core workflow
shannot run <script.py># Capture intent
shannot run -c "print(1+1)"# Inline code
shannot approve # Review and execute# Execute specific session
shannot run --session <id># Execute approved session
shannot run --session <id> --json-output # Machine-friendly# Remote execution
shannot run <script.py> --target user@host
# Setup
shannot setup # Interactive menu
shannot setup runtime # Install PyPy sandbox
shannot setup remote add prod admin@prod.example.com
shannot setup remote test prod
shannot setup mcp install # Claude Desktop integration# Status
shannot status # Runtime, config, pending sessions# Rollback
shannot rollback <session_id># Restore files to pre-execution state
shannot checkpoint list # List sessions with checkpoints
shannot checkpoint show <id># Show checkpoint detailsSingle TOML file: ~/.config/shannot/config.toml (or .shannot/config.toml per-project)
[profile]
auto_approve = [
"ls", "cat", "head", "tail", "df", "ps", "grep", "find",
"systemctl status", "journalctl",
]
always_deny = [
"rm -rf /", "rm -rf ~", "dd if=", "mkfs",
"curl | sh", "wget | bash",
]
[audit]
enabled = truerotation = "daily"max_files = 30
[remotes.prod]
host = "prod.example.com"user = "admin"
[remotes.staging]
host = "staging.local"user = "deploy"| Approach | Trade-off |
|---|---|
| VM/Container | Agent can't do real work — isolated from your actual system |
| WASM | Capability-restricted — limited to what you expose |
| Policy sandbox | Static rules — can't adapt to context |
| Shannot | Agent does real work, with human approval |
Shannot is collaborative, not adversarial. The agent helps you. You stay in control.
LLM-assisted sysadmin — Let Claude diagnose and fix server issues, with you approving each change
Safe exploration — Run unfamiliar scripts knowing you'll see exactly what they want to do
Audited automation — Every command and file write logged, nothing happens without approval
Teaching — Show students what scripts do before execution
Shannot provides supervised execution, not absolute isolation.
What it provides:
- System call interception via PyPy sandbox
- Virtual filesystem — scripts see only what you expose
- Command and file write approval workflow
- Conflict detection for file modifications
- Audit logging
What it doesn't provide:
- Memory/CPU limits (use cgroups separately)
- Network filtering (sockets are disabled entirely)
- Protection against PyPy sandbox escapes
For production, combine with:
- Dedicated service accounts (least privilege)
- Resource limits (systemd, cgroups)
- Network segmentation
See SECURITY.md for details.
Shannot includes an MCP server for Claude Desktop:
shannot setup mcp installThis lets Claude propose scripts directly, which you review and approve through the standard workflow.
Apache 2.0 — See LICENSE
See CONTRIBUTING.md