Shannot
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.
How It Works
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]
Quick Start
# Install
pip install shannot
# Run a script (captures what it wants to do)
shannot run fix-nginx.py
# Review and approve
shannot approve
That's it. Two commands.
Features
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 approve
Zero 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
Installation
# Recommended
pip install shannot
# Or with uv
uv tool install shannot
# Or with pipx
pipx install shannot
Requirements:
- Python 3.11+ (host system)
- Linux (sandbox execution) or macOS (remote execution only)
Note: Scripts run in Python 3.6 (the PyPy sandbox version).
CLI Reference
# 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 details
Configuration
Single 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 = true
rotation = "daily"
max_files = 30
[remotes.prod]
host = "prod.example.com"
user = "admin"
[remotes.staging]
host = "staging.local"
user = "deploy"
Why Not Just Use a Container?
| 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.
Use Cases
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
Security Model
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.
MCP Integration
Shannot includes an MCP server for Claude Desktop:
shannot setup mcp install
This lets Claude propose scripts directly, which you review and approve through the standard workflow.
License
Apache 2.0 — See LICENSE
Contributing
See CONTRIBUTING.md
Metadata
Release files for iflow-mcp_corv89-shannot 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_corv89_shannot-0.11.0.tar.gz | 128.7 kB | Without provenance | Details for iflow_mcp_corv89_shannot-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_corv89_shannot-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_corv89_shannot-0.11.0-py3-none-any.whl |
Total release size: 254.6 kB
Release files / iflow_mcp_corv89_shannot-0.11.0.tar.gz
| Download URL | iflow_mcp_corv89_shannot-0.11.0.tar.gz |
|---|---|
| Size | 128.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
01fb0e38b044dc8295d9310900ed47dc5bde9c2340df359d237bb25831e83a96
|
|
BLAKE2b-256 checksum How to use checksums |
c3706827605dc6692211d48343c6c86067278e93f44211fab4afcf9d74d35130
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_corv89_shannot-0.11.0-py3-none-any.whl
| Download URL | iflow_mcp_corv89_shannot-0.11.0-py3-none-any.whl |
|---|---|
| Size | 126.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4ee3993729b272062cd27c8a0441a99d9e15fb1a09c25c8983a8075e6a306b48
|
|
BLAKE2b-256 checksum How to use checksums |
76c884fec572db1bb669cede3e927c62c9f027a27767175f655e89cf09a11675
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_corv89-shannot 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.