https://github.com/brooksomics/llm-rustyolo
Secure Docker wrapper for AI coding agents with filesystem, privilege, and network isolation
https://github.com/brooksomics/llm-rustyolo
ai ai-agents anthropic claude claude-code coding-assistant containers docker firewall llm network-isolation rust sandbox security
Last synced: 5 months ago
JSON representation
Secure Docker wrapper for AI coding agents with filesystem, privilege, and network isolation
- Host: GitHub
- URL: https://github.com/brooksomics/llm-rustyolo
- Owner: brooksomics
- Created: 2025-11-06T23:06:43.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-06T23:08:55.000Z (7 months ago)
- Last Synced: 2025-11-07T01:09:02.680Z (7 months ago)
- Topics: ai, ai-agents, anthropic, claude, claude-code, coding-assistant, containers, docker, firewall, llm, network-isolation, rust, sandbox, security
- Language: Rust
- Homepage: https://www.bubbabrooks.info/
- Size: 1.4 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# llm-rustyolo: A Secure, Firewalled Agent Runner
This project provides a robust, secure wrapper for running AI agents like Claude Code in "YOLO mode" (`--dangerously-skip-permissions`) by solving the entire [lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/):
🔒 **Filesystem Isolation**: The agent only sees your project directory and explicitly mounted volumes (like read-only `~/.ssh`). It cannot see your host filesystem.
👤 **Privilege Isolation**: The agent runs as a powerless, non-root `agent` user inside the container, with file permissions matched to your host user.
🔥 **Network Isolation**: A dynamic iptables firewall is built at startup, blocking all outbound network traffic except for DNS and a list of trusted domains you provide.
This tool is heavily inspired by [deva.sh](https://github.com/thevibeworks/deva) and Simon Willison's ["Living dangerously with Claude"](https://simonwillison.net/2025/Oct/22/living-dangerously-with-claude/).
## Architecture
This project has two parts:
1. **A Rust CLI (`rustyolo`)**: This is the wrapper you run on your host machine. It parses your arguments (volumes, network rules, auth paths) and programmatically constructs a secure `docker run` command.
2. **A Docker Image (`llm-rustyolo`)**: This image contains the agents (Claude Code, etc.) and an `entrypoint.sh` script. The script uses the arguments from the Rust CLI to build the firewall, fix file permissions, and then run the agent as a non-root user.
This approach combines the flexible auth and volume mounting from deva.sh with the strict network firewall we developed.
## Quick Setup
### Prerequisites
- **Homebrew** (for macOS/Linux users) - Install from https://brew.sh
- **Docker** (Docker Desktop on macOS, or docker.io on Linux)
### Installation
#### Option 1: Homebrew (Recommended for macOS/Linux)
```bash
# Install via Homebrew tap
brew tap brooksomics/rustyolo
brew install rustyolo
# Pull the Docker image
docker pull ghcr.io/brooksomics/llm-rustyolo:latest
```
Or build locally if you need to customize:
```bash
git clone https://github.com/brooksomics/llm-rustyolo.git
cd llm-rustyolo
docker build -t ghcr.io/brooksomics/llm-rustyolo:latest .
```
#### Option 2: Manual Build (For customization or other platforms)
```bash
# 1. Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 2. Build the Rust CLI
cargo build --release
sudo cp target/release/rustyolo /usr/local/bin/
# 3. Pull the Docker image
docker pull ghcr.io/brooksomics/llm-rustyolo:latest
# Or build locally if you need to customize
docker build -t ghcr.io/brooksomics/llm-rustyolo:latest .
```
For detailed installation instructions, see [docs/guides/installation.md](./docs/guides/installation.md).
## Usage
Once set up, you can go to any project directory and run your agent.
### Example: Running Claude with Network Access
This is the most common use case. It allows the agent to access github.com (for git pull) and pypi.org (for pip install) but nothing else.
```bash
cd ~/my-new-project
rustyolo \
--allow-domains "github.com api.github.com pypi.org files.pythonhosted.org" \
-v ~/.ssh:/home/agent/.ssh:ro \
-v ~/.gitconfig:/home/agent/.gitconfig:ro \
--auth-home ~/.config/rustyolo \
claude
```
### Example: Running with No Network
This runs Claude with zero internet access.
```bash
rustyolo \
-v ~/.ssh:/home/agent/.ssh:ro \
--auth-home ~/.config/rustyolo \
claude
```
### Example: Running a Custom Command
You can pass any command and arguments after the agent name. `rustyolo` is smart enough to see you provided args and won't add its default "danger" flag.
```bash
rustyolo claude --help
```
## Configuration Files
Tired of typing long commands? Create a `.rustyolo.toml` file in your project directory:
```toml
[default]
allow_domains = "github.com pypi.org npmjs.org"
volumes = ["~/.ssh:/home/agent/.ssh:ro", "~/.gitconfig:/home/agent/.gitconfig:ro"]
auth_home = "~/.config/rustyolo"
[resources]
memory = "8g"
cpus = "6"
[security]
audit_log = "basic"
```
Then just run:
```bash
rustyolo claude
```
**Features:**
- ✅ Automatic loading from current directory
- ✅ CLI arguments override config file settings
- ✅ Gitignored by default (project-specific settings)
- ✅ Full validation with helpful error messages
See [docs/guides/configuration.md](./docs/guides/configuration.md) for detailed configuration guide and examples.
## Keeping Up-to-Date
### Homebrew Installation
If you installed via Homebrew, you have multiple update options:
```bash
# Update Docker image only (shows reminder about CLI)
rustyolo update
# Update just the Docker image
rustyolo update --image
# Update the CLI binary (must use Homebrew)
brew upgrade rustyolo
```
**Note:** The `rustyolo update` command only updates the Docker image for Homebrew installations, as Homebrew manages the CLI binary separately. You'll see a reminder to run `brew upgrade rustyolo` for the CLI.
### Manual Installation
If you built from source, use the built-in update commands:
```bash
# Update the binary
rustyolo update --binary
# Update the Docker image
rustyolo update --image
# Update both
rustyolo update
```
The tool automatically checks for updates on startup and notifies you when a new version is available.
## All CLI Options
```
A secure, firewalled Docker wrapper for AI agents.
Usage: rustyolo [OPTIONS] [AGENT] [AGENT_ARGS]...
rustyolo update [OPTIONS]
Subcommands:
update Update rustyolo components (binary and/or Docker image)
Arguments:
[AGENT]
The agent to run (e.g., 'claude')
[default: claude]
[AGENT_ARGS]...
Arguments to pass directly to the agent (e.g., --help or -p "prompt")
Options:
-v, --volume
Additional volumes to mount (e.g., -v ~/.ssh:/home/agent/.ssh:ro)
-e, --env
Environment variables to pass (e.g., -e MY_VAR=value)
--allow-domains
Space-separated list of domains to allow outbound traffic to.
All other traffic (except DNS) will be blocked.
Example: --allow-domains "github.com pypi.org npmjs.com"
Note: Anthropic domains are automatically added when using Claude.
[env: TRUSTED_DOMAINS=]
--auth-home
Mount a persistent auth directory. Maps your local dir
to '/home/agent/.config/rustyolo' in the container.
Recommended: ~/.config/rustyolo
--image
The Docker image to use
[default: llm-rustyolo:latest]
--skip-version-check
Skip automatic version check on startup
-h, --help
Print help
-V, --version
Print version
```
## Documentation
- [docs/guides/installation.md](./docs/guides/installation.md) - Detailed installation instructions
- [docs/guides/configuration.md](./docs/guides/configuration.md) - Configuration file guide
- [CLAUDE.md](./CLAUDE.md) - Complete documentation on how it works, security considerations, and advanced usage
- [docs/security/security-policy.md](./docs/security/security-policy.md) - Secret scanning and security protection setup
- [docs/security/seccomp.md](./docs/security/seccomp.md) - Seccomp profiles and syscall filtering
- [docs/](./docs/) - Full documentation index
## Security
This repository implements multiple layers of secret detection to prevent accidentally committing sensitive information:
- **Pre-commit Hooks** - Gitleaks, detect-secrets, and more run before each commit
- **GitHub Actions** - Automated secret scanning on every push and PR
- **git-secrets** - Additional local protection with custom patterns
See [docs/security/security-policy.md](./docs/security/security-policy.md) for complete setup instructions and best practices.
## License
MIT License
## Contributing
Contributions welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.