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!

🔒 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

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

# Install UV (recommended - works on all platforms)
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]"

If your target is a remote Linux system, bubblewrap is all you need (Python not required):

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora/RHEL
sudo dnf install bubblewrap

# openSUSE
sudo zypper install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

If client and target are the same Linux machine, install both shannot and bubblewrap.

See Deployment Guide for remote execution setup via SSH.

# 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
pipx install "shannot[all]"  # All optional features

# Basic installation
pip install --user shannot

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

# Note: On Ubuntu/Debian, you may need --break-system-packages
# (not recommended, use pipx or uv instead)

Optional dependencies:

• [mcp] - MCP server for Claude Desktop integration
• [all] - All optional features

# Run a command in the sandbox
shannot ls /

# Check version
shannot --version

# Verify the sandbox is working
shannot verify

# Export your profile configuration
shannot export

# Use a custom profile
shannot --profile /path/to/profile.json cat /etc/os-release

# Get help
shannot --help

System diagnostics - Let LLM agents inspect system state without modification risk Safe exploration - Test unfamiliar commands without worrying about side effects Automated monitoring - Build scripts with guaranteed read-only access

# Diagnostics
shannot df -h
shannot cat /proc/meminfo
shannot systemctl status

# Exploration
shannot find / -name "*.conf"
shannot grep -r "pattern" /var/log

# Monitoring scripts
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(["df", "-h"])
if result.succeeded():
    print(result.stdout)

Shannot uses JSON profiles to control sandbox behavior. Three profiles included:

• minimal.json (default) - Basic commands (ls, cat, grep, find), works out-of-the-box
• readonly.json - Extended command set, suitable for most use cases
• diagnostics.json - System monitoring (df, free, ps, uptime), perfect for LLM agents

{
  "name": "minimal",
  "allowed_commands": ["ls", "cat", "grep", "find"],
  "binds": [{"source": "/usr", "target": "/usr", "read_only": true}],
  "tmpfs_paths": ["/tmp"],
  "environment": {"PATH": "/usr/bin:/bin"},
  "network_isolation": true
}

See profiles for complete documentation.

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

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

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 for complete documentation.

# Clone and install
git clone https://github.com/corv89/shannot.git
cd shannot
make install-dev

# Run tests (integration tests require Linux + bubblewrap)
make test
make test-unit  # unit tests only

# Lint and type check
make lint
make format
make type-check

# Optional helpers
make test-integration
make test-coverage
make pre-commit-install  # re-install git hooks if needed

Full documentation

Quick links:

• Installation Guide - Install Shannot on any platform
• Usage Guide - Learn basic commands and workflows
• Profile Configuration - Configure sandbox behavior
• API Reference - Python API documentation
• Deployment Guide - Remote execution, Ansible, systemd
• MCP Integration - Claude Desktop integration
• Troubleshooting - Common issues and solutions

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

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 (seccomp), and resource limits.

Apache 2.0 - See LICENSE

Built on Bubblewrap and libseccomp