Shannot¶

Shannot lets LLM agents and automated tools safely explore your Linux systems without risk of modification. Built on bubblewrap, it provides bulletproof read-only 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 Claude Desktop Plug-and-play MCP integration - give Claude safe read-only access to your servers

Control Remote Systems Run sandboxed commands on Linux servers from your macOS or Windows laptop via SSH

Deploy in Minutes Python client + bubblewrap on target • No containers, VMs, or complex setup required

Quick Start¶

Installation¶

Client (any platform): Python 3.10+ Target (Linux only): bubblewrap

UV (Recommended)pipx (Ubuntu/Debian)pip

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# Or for Windows: irm https://astral.sh/uv/install.ps1 | iex

# Install shannot
uv tool install shannot

# Or with MCP support for Claude Desktop
uv tool install "shannot[mcp]"

# Install pipx
sudo apt install pipx
pipx ensurepath

# Install shannot
pipx install shannot

# Or with optional dependencies
pipx install "shannot[mcp]"  # MCP/Claude Desktop support

# Basic installation
pip install --user shannot

# With optional dependencies
pip install --user "shannot[mcp]"  # MCP/Claude Desktop support

Install bubblewrap (Linux only)¶

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora/RHEL
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

See Installation Guide for detailed instructions.

Basic Usage¶

# Run a command in read-only sandbox
shannot ls /

# Verify bubblewrap is available
shannot verify

# Export MCP configuration for Claude Desktop
shannot export

See Usage Guide for more examples.

How It Works¶

Shannot wraps Linux's bubblewrap tool to create lightweight, secure sandboxes:

Namespace isolation - Each command runs in isolated namespaces (PID, mount, network, etc.)
Read-only mounts - System directories are mounted read-only
Temporary filesystems - Writable locations use ephemeral tmpfs
Command allowlisting - Only explicitly permitted commands can execute
No persistence - All changes are lost when the command exits

Python API¶

from shannot import SandboxManager, load_profile_from_path

profile = load_profile_from_path("~/.config/shannot/profile.json")
manager = SandboxManager(profile, Path("/usr/bin/bwrap"))

result = manager.run(["ls", "/"])
print(f"Output: {result.stdout}")
print(f"Duration: {result.duration:.2f}s")

See API Reference for complete documentation.

Documentation¶

Installation Guide - Install Shannot on any platform
Usage Guide - Learn basic commands and workflows
Profile Configuration - Configure sandbox behavior
Configuration - Remote execution, Ansible, systemd
Deployment - Production deployment guide
MCP Integration - Claude Desktop setup
API Reference - Python API documentation
Testing - Running and writing tests
Troubleshooting - Common issues and solutions

Security Considerations¶

Shannot provides strong isolation but is not a security boundary:

Sandbox escapes possible via kernel exploits
Read-only access still exposes system information
No built-in CPU/memory limits (use systemd/cgroups)
Don't run as root unless necessary

For production, combine with SELinux/AppArmor, seccomp filters, and resource limits.

Contributing¶

Contributions welcome! See CONTRIBUTING.md or open an issue.

License¶

Apache 2.0 - See LICENSE

Built on Bubblewrap and libseccomp