# Shannot Sandbox
[](https://github.com/corv89/shannot/actions/workflows/test.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://www.kernel.org/)
**Shannot** lets LLM agents and automated tools safely explore your Linux systems without risk of modification. Built on [bubblewrap](https://github.com/containers/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](https://corv89.github.io/shannot/mcp/)
* 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
#### Install on Client (any platform)
```bash
# 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]"
```
#### Install on Target (Linux only)
If your target is a remote Linux system, bubblewrap is all you need (Python not required):
```bash
# 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](https://corv89.github.io/shannot/deployment/) for remote execution setup via SSH.
<details>
<summary><b>Alternative installation methods</b></summary>
**pipx (recommended for Ubuntu/Debian):**
Ubuntu and Debian mark system Python as "externally managed" (PEP 668), which prevents `pip install --user`. Use `pipx` instead:
```bash
# 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
```
**Traditional pip:**
```bash
# 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)
```
</details>
**Optional dependencies:**
- `[mcp]` - MCP server for Claude Desktop integration
- `[all]` - All optional features
### Usage
```bash
# 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
```
## Use Cases
**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
```bash
# Diagnostics
shannot df -h
shannot cat /proc/meminfo
shannot systemctl status
# Exploration
shannot find / -name "*.conf"
shannot grep -r "pattern" /var/log
```
```python
# 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)
```
## Configuration
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
```json
{
"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](https://corv89.github.io/shannot/profiles) for complete documentation.
## How It Works
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
## Python API
```python
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](https://corv89.github.io/shannot/api) for complete documentation.
## Development
```bash
# 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
```
## Documentation
**[Full documentation](https://corv89.github.io/shannot/)**
Quick links:
- **[Installation Guide](https://corv89.github.io/shannot/installation/)** - Install Shannot on any platform
- **[Usage Guide](https://corv89.github.io/shannot/usage/)** - Learn basic commands and workflows
- **[Profile Configuration](https://corv89.github.io/shannot/profiles/)** - Configure sandbox behavior
- **[API Reference](https://corv89.github.io/shannot/api/)** - Python API documentation
- **[Deployment Guide](https://corv89.github.io/shannot/deployment/)** - Remote execution, Ansible, systemd
- **[MCP Integration](https://corv89.github.io/shannot/mcp/)** - Claude Desktop integration
- **[Troubleshooting](https://corv89.github.io/shannot/troubleshooting/)** - Common issues and solutions
## Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) or [open an issue](https://github.com/corv89/shannot/issues).
## 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 ([seccomp](https://corv89.github.io/shannot/seccomp)), and resource limits.
## License
Apache 2.0 - See [LICENSE](LICENSE)
Built on [Bubblewrap](https://github.com/containers/bubblewrap) and [libseccomp](https://github.com/seccomp/libseccomp)
Raw data
{
"_id": null,
"home_page": null,
"name": "shannot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "sandbox, bubblewrap, security, read-only, llm, diagnostics",
"author": null,
"author_email": "corv89 <corv89@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/c0/24/c94dd1d495369be3d2391a0788c80b0053a703c30c2bfb5a82f83a843f93/shannot-0.2.1.tar.gz",
"platform": null,
"description": "# Shannot Sandbox\n\n[](https://github.com/corv89/shannot/actions/workflows/test.yml)\n[](LICENSE)\n[](https://www.python.org/downloads/)\n[](https://www.kernel.org/)\n\n**Shannot** lets LLM agents and automated tools safely explore your Linux systems without risk of modification. Built on [bubblewrap](https://github.com/containers/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.\n\n> Claude __shannot__ do *that!*\n\n## Features\n\n\ud83d\udd12 **Run Untrusted Commands Safely**\n* Let LLM agents explore your system without risk of modification\n* Network-isolated execution\n* Control exactly which commands are allowed\n\n\ud83e\udd16 **Works with Claude Desktop**\n* Plug-and-play [MCP integration](https://corv89.github.io/shannot/mcp/)\n* Give Claude safe read-only access to your servers\n\n\ud83c\udf10 **Control Remote Systems**\n* Run sandboxed commands on Linux servers from your macOS or Windows laptop via SSH\n\n\u26a1 **Deploy in Minutes**\n* Python client + bubblewrap on target\n* No containers, VMs, or complex setup required\n\n\n## Quick Start\n\n### Installation\n\n- **Client** (any platform): Python 3.10+\n- **Target** (Linux only): bubblewrap\n\n#### Install on Client (any platform)\n\n```bash\n# Install UV (recommended - works on all platforms)\ncurl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux\n# Or for Windows: irm https://astral.sh/uv/install.ps1 | iex\n\n# Install shannot\nuv tool install shannot\n\n# Or with MCP support for Claude Desktop\nuv tool install \"shannot[mcp]\"\n```\n\n#### Install on Target (Linux only)\n\nIf your target is a remote Linux system, bubblewrap is all you need (Python not required):\n\n```bash\n# Debian/Ubuntu\nsudo apt install bubblewrap\n\n# Fedora/RHEL\nsudo dnf install bubblewrap\n\n# openSUSE\nsudo zypper install bubblewrap\n\n# Arch Linux\nsudo pacman -S bubblewrap\n```\n\nIf client and target are the same Linux machine, install both shannot and bubblewrap.\n\nSee [Deployment Guide](https://corv89.github.io/shannot/deployment/) for remote execution setup via SSH.\n\n<details>\n<summary><b>Alternative installation methods</b></summary>\n\n**pipx (recommended for Ubuntu/Debian):**\n\nUbuntu and Debian mark system Python as \"externally managed\" (PEP 668), which prevents `pip install --user`. Use `pipx` instead:\n\n```bash\n# Install pipx\nsudo apt install pipx\npipx ensurepath\n\n# Install shannot\npipx install shannot\n\n# Or with optional dependencies\npipx install \"shannot[mcp]\" # MCP/Claude Desktop support\npipx install \"shannot[all]\" # All optional features\n```\n\n**Traditional pip:**\n\n```bash\n# Basic installation\npip install --user shannot\n\n# With optional dependencies\npip install --user \"shannot[mcp]\" # MCP/Claude Desktop support\npip install --user \"shannot[all]\" # All optional features\n\n# Note: On Ubuntu/Debian, you may need --break-system-packages\n# (not recommended, use pipx or uv instead)\n```\n</details>\n\n**Optional dependencies:**\n- `[mcp]` - MCP server for Claude Desktop integration\n- `[all]` - All optional features\n\n### Usage\n\n```bash\n# Run a command in the sandbox\nshannot ls /\n\n# Check version\nshannot --version\n\n# Verify the sandbox is working\nshannot verify\n\n# Export your profile configuration\nshannot export\n\n# Use a custom profile\nshannot --profile /path/to/profile.json cat /etc/os-release\n\n# Get help\nshannot --help\n```\n\n## Use Cases\n\n**System diagnostics** - Let LLM agents inspect system state without modification risk\n**Safe exploration** - Test unfamiliar commands without worrying about side effects\n**Automated monitoring** - Build scripts with guaranteed read-only access\n\n```bash\n# Diagnostics\nshannot df -h\nshannot cat /proc/meminfo\nshannot systemctl status\n\n# Exploration\nshannot find / -name \"*.conf\"\nshannot grep -r \"pattern\" /var/log\n```\n\n```python\n# Monitoring scripts\nfrom shannot import SandboxManager, load_profile_from_path\n\nprofile = load_profile_from_path(\"~/.config/shannot/profile.json\")\nmanager = SandboxManager(profile, Path(\"/usr/bin/bwrap\"))\n\nresult = manager.run([\"df\", \"-h\"])\nif result.succeeded():\n print(result.stdout)\n```\n\n## Configuration\n\nShannot uses JSON profiles to control sandbox behavior. Three profiles included:\n\n- **`minimal.json`** (default) - Basic commands (ls, cat, grep, find), works out-of-the-box\n- **`readonly.json`** - Extended command set, suitable for most use cases\n- **`diagnostics.json`** - System monitoring (df, free, ps, uptime), perfect for LLM agents\n\n```json\n{\n \"name\": \"minimal\",\n \"allowed_commands\": [\"ls\", \"cat\", \"grep\", \"find\"],\n \"binds\": [{\"source\": \"/usr\", \"target\": \"/usr\", \"read_only\": true}],\n \"tmpfs_paths\": [\"/tmp\"],\n \"environment\": {\"PATH\": \"/usr/bin:/bin\"},\n \"network_isolation\": true\n}\n```\n\nSee [profiles](https://corv89.github.io/shannot/profiles) for complete documentation.\n\n## How It Works\n\nShannot wraps Linux's bubblewrap tool to create lightweight, secure sandboxes:\n\n1. **Namespace isolation** - Each command runs in isolated namespaces (PID, mount, network, etc.)\n2. **Read-only mounts** - System directories are mounted read-only\n3. **Temporary filesystems** - Writable locations use ephemeral tmpfs\n4. **Command allowlisting** - Only explicitly permitted commands can execute\n5. **No persistence** - All changes are lost when the command exits\n\n## Python API\n\n```python\nfrom shannot import SandboxManager, load_profile_from_path\n\nprofile = load_profile_from_path(\"~/.config/shannot/profile.json\")\nmanager = SandboxManager(profile, Path(\"/usr/bin/bwrap\"))\n\nresult = manager.run([\"ls\", \"/\"])\nprint(f\"Output: {result.stdout}\")\nprint(f\"Duration: {result.duration:.2f}s\")\n```\n\nSee [api](https://corv89.github.io/shannot/api) for complete documentation.\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/corv89/shannot.git\ncd shannot\nmake install-dev\n\n# Run tests (integration tests require Linux + bubblewrap)\nmake test\nmake test-unit # unit tests only\n\n# Lint and type check\nmake lint\nmake format\nmake type-check\n\n# Optional helpers\nmake test-integration\nmake test-coverage\nmake pre-commit-install # re-install git hooks if needed\n```\n\n\n## Documentation\n\n**[Full documentation](https://corv89.github.io/shannot/)**\n\nQuick links:\n- **[Installation Guide](https://corv89.github.io/shannot/installation/)** - Install Shannot on any platform\n- **[Usage Guide](https://corv89.github.io/shannot/usage/)** - Learn basic commands and workflows\n- **[Profile Configuration](https://corv89.github.io/shannot/profiles/)** - Configure sandbox behavior\n- **[API Reference](https://corv89.github.io/shannot/api/)** - Python API documentation\n- **[Deployment Guide](https://corv89.github.io/shannot/deployment/)** - Remote execution, Ansible, systemd\n- **[MCP Integration](https://corv89.github.io/shannot/mcp/)** - Claude Desktop integration\n- **[Troubleshooting](https://corv89.github.io/shannot/troubleshooting/)** - Common issues and solutions\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) or [open an issue](https://github.com/corv89/shannot/issues).\n\n## Security Considerations\n\nShannot provides strong isolation but **is not a security boundary**:\n\n- Sandbox escapes possible via kernel exploits\n- Read-only access still exposes system information\n- No built-in CPU/memory limits (use systemd/cgroups)\n- Don't run as root unless necessary\n\nFor production, combine with SELinux/AppArmor, seccomp filters ([seccomp](https://corv89.github.io/shannot/seccomp)), and resource limits.\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE)\n\nBuilt on [Bubblewrap](https://github.com/containers/bubblewrap) and [libseccomp](https://github.com/seccomp/libseccomp)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Secure read-only sandboxing for LLM agents and system diagnostics",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/corv89/shannot/issues",
"Documentation": "https://github.com/corv89/shannot/blob/main/README.md",
"Homepage": "https://github.com/corv89/shannot",
"Repository": "https://github.com/corv89/shannot"
},
"split_keywords": [
"sandbox",
" bubblewrap",
" security",
" read-only",
" llm",
" diagnostics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "16edfc685ac2f66d2ed74bdb006991f2247961c94450925616ddbbaea1ce6719",
"md5": "b5386ea8fb8ce7bb58c5b6244379bf61",
"sha256": "9b42daf87930d1599f23cfee1f6c829997b67dfd85486b4e30abbdc504689da3"
},
"downloads": -1,
"filename": "shannot-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5386ea8fb8ce7bb58c5b6244379bf61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 48688,
"upload_time": "2025-10-25T08:05:17",
"upload_time_iso_8601": "2025-10-25T08:05:17.369417Z",
"url": "https://files.pythonhosted.org/packages/16/ed/fc685ac2f66d2ed74bdb006991f2247961c94450925616ddbbaea1ce6719/shannot-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c024c94dd1d495369be3d2391a0788c80b0053a703c30c2bfb5a82f83a843f93",
"md5": "22edac0ca37a53097b9563f6ff805219",
"sha256": "52ce25691cd054fa64d705bbaaad95901427da6d12228a6ae7ffd4d2859e13d3"
},
"downloads": -1,
"filename": "shannot-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "22edac0ca37a53097b9563f6ff805219",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 65936,
"upload_time": "2025-10-25T08:05:18",
"upload_time_iso_8601": "2025-10-25T08:05:18.530167Z",
"url": "https://files.pythonhosted.org/packages/c0/24/c94dd1d495369be3d2391a0788c80b0053a703c30c2bfb5a82f83a843f93/shannot-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 08:05:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "corv89",
"github_project": "shannot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shannot"
}
JSON
