{"id":32848648,"url":"https://github.com/brooksomics/llm-rustyolo","last_synced_at":"2026-01-24T01:18:22.661Z","repository":{"id":322900471,"uuid":"1091360613","full_name":"brooksomics/llm-rustyolo","owner":"brooksomics","description":"Secure Docker wrapper for AI coding agents with filesystem, privilege, and network isolation","archived":false,"fork":false,"pushed_at":"2025-11-06T23:08:55.000Z","size":1466,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-07T01:09:02.680Z","etag":null,"topics":["ai","ai-agents","anthropic","claude","claude-code","coding-assistant","containers","docker","firewall","llm","network-isolation","rust","sandbox","security"],"latest_commit_sha":null,"homepage":"https://www.bubbabrooks.info/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brooksomics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T23:06:43.000Z","updated_at":"2025-11-06T23:16:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brooksomics/llm-rustyolo","commit_stats":null,"previous_names":["brooksomics/llm-rustyolo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/brooksomics/llm-rustyolo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooksomics%2Fllm-rustyolo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooksomics%2Fllm-rustyolo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooksomics%2Fllm-rustyolo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooksomics%2Fllm-rustyolo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brooksomics","download_url":"https://codeload.github.com/brooksomics/llm-rustyolo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brooksomics%2Fllm-rustyolo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283333707,"owners_count":26818628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-08T02:00:06.281Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","anthropic","claude","claude-code","coding-assistant","containers","docker","firewall","llm","network-isolation","rust","sandbox","security"],"created_at":"2025-11-08T10:00:42.170Z","updated_at":"2026-01-24T01:18:22.653Z","avatar_url":"https://github.com/brooksomics.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# llm-rustyolo: A Secure, Firewalled Agent Runner\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/mascot.png\" alt=\"RustyYOLO Mascot\" width=\"400\"\u003e\n\u003c/p\u003e\n\nThis 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/):\n\n🔒 **Filesystem Isolation**: The agent only sees your project directory and explicitly mounted volumes (like read-only `~/.ssh`). It cannot see your host filesystem.\n\n👤 **Privilege Isolation**: The agent runs as a powerless, non-root `agent` user inside the container, with file permissions matched to your host user.\n\n🔥 **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.\n\nThis 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/).\n\n## Architecture\n\nThis project has two parts:\n\n1. **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.\n\n2. **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.\n\nThis approach combines the flexible auth and volume mounting from deva.sh with the strict network firewall we developed.\n\n## Quick Setup\n\n### Prerequisites\n- **Homebrew** (for macOS/Linux users) - Install from https://brew.sh\n- **Docker** (Docker Desktop on macOS, or docker.io on Linux)\n\n### Installation\n\n#### Option 1: Homebrew (Recommended for macOS/Linux)\n\n```bash\n# Install via Homebrew tap\nbrew tap brooksomics/rustyolo\nbrew install rustyolo\n\n# Pull the Docker image\ndocker pull ghcr.io/brooksomics/llm-rustyolo:latest\n```\n\nOr build locally if you need to customize:\n```bash\ngit clone https://github.com/brooksomics/llm-rustyolo.git\ncd llm-rustyolo\ndocker build -t ghcr.io/brooksomics/llm-rustyolo:latest .\n```\n\n#### Option 2: Manual Build (For customization or other platforms)\n\n```bash\n# 1. Install Rust (if not already installed)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# 2. Build the Rust CLI\ncargo build --release\nsudo cp target/release/rustyolo /usr/local/bin/\n\n# 3. Pull the Docker image\ndocker pull ghcr.io/brooksomics/llm-rustyolo:latest\n\n# Or build locally if you need to customize\ndocker build -t ghcr.io/brooksomics/llm-rustyolo:latest .\n```\n\nFor detailed installation instructions, see [docs/guides/installation.md](./docs/guides/installation.md).\n\n## Usage\n\nOnce set up, you can go to any project directory and run your agent.\n\n### Example: Running Claude with Network Access\n\nThis 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.\n\n```bash\ncd ~/my-new-project\n\nrustyolo \\\n  --allow-domains \"github.com api.github.com pypi.org files.pythonhosted.org\" \\\n  -v ~/.ssh:/home/agent/.ssh:ro \\\n  -v ~/.gitconfig:/home/agent/.gitconfig:ro \\\n  --auth-home ~/.config/rustyolo \\\n  claude\n```\n\n### Example: Running with No Network\n\nThis runs Claude with zero internet access.\n\n```bash\nrustyolo \\\n  -v ~/.ssh:/home/agent/.ssh:ro \\\n  --auth-home ~/.config/rustyolo \\\n  claude\n```\n\n### Example: Running a Custom Command\n\nYou 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.\n\n```bash\nrustyolo claude --help\n```\n\n## Configuration Files\n\nTired of typing long commands? Create a `.rustyolo.toml` file in your project directory:\n\n```toml\n[default]\nallow_domains = \"github.com pypi.org npmjs.org\"\nvolumes = [\"~/.ssh:/home/agent/.ssh:ro\", \"~/.gitconfig:/home/agent/.gitconfig:ro\"]\nauth_home = \"~/.config/rustyolo\"\n\n[resources]\nmemory = \"8g\"\ncpus = \"6\"\n\n[security]\naudit_log = \"basic\"\n```\n\nThen just run:\n```bash\nrustyolo claude\n```\n\n**Features:**\n- ✅ Automatic loading from current directory\n- ✅ CLI arguments override config file settings\n- ✅ Gitignored by default (project-specific settings)\n- ✅ Full validation with helpful error messages\n\nSee [docs/guides/configuration.md](./docs/guides/configuration.md) for detailed configuration guide and examples.\n\n## Keeping Up-to-Date\n\n### Homebrew Installation\n\nIf you installed via Homebrew, you have multiple update options:\n\n```bash\n# Update Docker image only (shows reminder about CLI)\nrustyolo update\n\n# Update just the Docker image\nrustyolo update --image\n\n# Update the CLI binary (must use Homebrew)\nbrew upgrade rustyolo\n```\n\n**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.\n\n### Manual Installation\n\nIf you built from source, use the built-in update commands:\n\n```bash\n# Update the binary\nrustyolo update --binary\n\n# Update the Docker image\nrustyolo update --image\n\n# Update both\nrustyolo update\n```\n\nThe tool automatically checks for updates on startup and notifies you when a new version is available.\n\n## All CLI Options\n\n```\nA secure, firewalled Docker wrapper for AI agents.\n\nUsage: rustyolo [OPTIONS] [AGENT] [AGENT_ARGS]...\n       rustyolo update [OPTIONS]\n\nSubcommands:\n  update    Update rustyolo components (binary and/or Docker image)\n\nArguments:\n  [AGENT]\n          The agent to run (e.g., 'claude')\n          [default: claude]\n\n  [AGENT_ARGS]...\n          Arguments to pass directly to the agent (e.g., --help or -p \"prompt\")\n\nOptions:\n  -v, --volume \u003cVOLUMES\u003e\n          Additional volumes to mount (e.g., -v ~/.ssh:/home/agent/.ssh:ro)\n\n  -e, --env \u003cENVS\u003e\n          Environment variables to pass (e.g., -e MY_VAR=value)\n\n  --allow-domains \u003cALLOW_DOMAINS\u003e\n          Space-separated list of domains to allow outbound traffic to.\n          All other traffic (except DNS) will be blocked.\n          Example: --allow-domains \"github.com pypi.org npmjs.com\"\n          Note: Anthropic domains are automatically added when using Claude.\n          [env: TRUSTED_DOMAINS=]\n\n  --auth-home \u003cAUTH_HOME\u003e\n          Mount a persistent auth directory. Maps your local dir\n          to '/home/agent/.config/rustyolo' in the container.\n          Recommended: ~/.config/rustyolo\n\n  --image \u003cIMAGE\u003e\n          The Docker image to use\n          [default: llm-rustyolo:latest]\n\n  --skip-version-check\n          Skip automatic version check on startup\n\n  -h, --help\n          Print help\n\n  -V, --version\n          Print version\n```\n\n## Documentation\n\n- [docs/guides/installation.md](./docs/guides/installation.md) - Detailed installation instructions\n- [docs/guides/configuration.md](./docs/guides/configuration.md) - Configuration file guide\n- [CLAUDE.md](./CLAUDE.md) - Complete documentation on how it works, security considerations, and advanced usage\n- [docs/security/security-policy.md](./docs/security/security-policy.md) - Secret scanning and security protection setup\n- [docs/security/seccomp.md](./docs/security/seccomp.md) - Seccomp profiles and syscall filtering\n- [docs/](./docs/) - Full documentation index\n\n## Security\n\nThis repository implements multiple layers of secret detection to prevent accidentally committing sensitive information:\n\n- **Pre-commit Hooks** - Gitleaks, detect-secrets, and more run before each commit\n- **GitHub Actions** - Automated secret scanning on every push and PR\n- **git-secrets** - Additional local protection with custom patterns\n\nSee [docs/security/security-policy.md](./docs/security/security-policy.md) for complete setup instructions and best practices.\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrooksomics%2Fllm-rustyolo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrooksomics%2Fllm-rustyolo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrooksomics%2Fllm-rustyolo/lists"}