shannot 0.3.1

Secure read-only sandboxing for LLM agents and system diagnostics

Shannot Sandbox

Shannot lets LLM agents and automated tools safely explore your Linux systems without risk of modification. Built on bubblewrap, it provides hardened sandboxing for system diagnostics, monitoring, and exploration - perfect for giving Claude or other AI assistants safe access to your servers.

Claude shannot do that!

Features

🔒 Run Untrusted Commands Safely

• Let LLM agents explore your system without risk of modification
• Network-isolated execution
• Control exactly which commands are allowed

🤖 Works with your favorite LLMs

• Plug-and-play standards-compliant MCP integration
• Convenient auto-install for Claude Code, Codex, LM Studio and Claude Desktop
• Compatible with any local model that supports tool-calling

🌐 Control Remote Systems

• Run sandboxed commands on Linux servers from macOS, Windows or Linux via SSH

⚡ Deploy in Minutes

• Lightweight Python client + bubblewrap on target
• No containers, VMs, or complex setup required

Quick Start

# Install UV (recommended - handles Python 3.10+ requirement automatically)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Shannot
uv tool install shannot

# On Linux: install bubblewrap
sudo apt install bubblewrap  # Debian/Ubuntu
sudo dnf install bubblewrap  # Fedora/RHEL

# Run commands in sandbox
shannot ls /
shannot df -h
shannot cat /etc/os-release

Alternative: pip install shannot (requires Python 3.10+, may conflict with system package managers)

See Installation Guide for details.

Profiles

Control what commands are allowed with JSON profiles:

shannot ls /                          # Uses minimal.json (default)
shannot --profile diagnostics df -h   # System monitoring commands
shannot --profile systemd journalctl  # Journal access

See Profile Configuration for customization.

Python API

from shannot import SandboxManager, load_profile_from_path

profile = load_profile_from_path("diagnostics.json")
manager = SandboxManager(profile)

result = manager.run(["df", "-h"])
print(result.stdout)

See API Reference for details.

Documentation

📚 Full Documentation • Installation • MCP Integration • API Reference

Security Note

Shannot provides strong isolation but is not a security boundary. Don't run as root unless necessary. See SECURITY.md for details.

License

Apache 2.0 - See LICENSE

Built on Bubblewrap and libseccomp