Metadata-Version: 2.4
Name: shannot
Version: 0.3.1
Summary: Secure read-only sandboxing for LLM agents and system diagnostics
Author-email: corv89 <corv89@users.noreply.github.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/corv89/shannot
Project-URL: Repository, https://github.com/corv89/shannot
Project-URL: Bug Tracker, https://github.com/corv89/shannot/issues
Project-URL: Documentation, https://github.com/corv89/shannot/blob/main/README.md
Keywords: sandbox,bubblewrap,security,read-only,llm,diagnostics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.18.0
Requires-Dist: asyncssh>=2.14.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: tomli-w>=1.0.0
Provides-Extra: minimal
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: basedpyright>=1.0; extra == "dev"
Requires-Dist: types-setuptools; extra == "dev"
Requires-Dist: mkdocs>=1.5.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.0.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
Dynamic: license-file

# Shannot Sandbox

[![Tests](https://github.com/corv89/shannot/actions/workflows/test.yml/badge.svg)](https://github.com/corv89/shannot/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Linux](https://img.shields.io/badge/os-linux-green.svg)](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 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](https://corv89.github.io/shannot/mcp/)
* 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

```bash
# 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](https://corv89.github.io/shannot/installation/) for details.

## Profiles

Control what commands are allowed with JSON profiles:

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

See [Profile Configuration](https://corv89.github.io/shannot/profiles/) for customization.


## Python API

```python
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](https://corv89.github.io/shannot/api/) for details.


## Documentation

📚 [**Full Documentation**](https://corv89.github.io/shannot/) • [Installation](https://corv89.github.io/shannot/installation/) • [MCP Integration](https://corv89.github.io/shannot/mcp/) • [API Reference](https://corv89.github.io/shannot/api/)

## Security Note

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

## License

Apache 2.0 - See [LICENSE](LICENSE)

Built on [Bubblewrap](https://github.com/containers/bubblewrap) and [libseccomp](https://github.com/seccomp/libseccomp)
