https://github.com/tnfru/autobox
Sandbox Claude Instance without exposing Git
https://github.com/tnfru/autobox
Last synced: 28 days ago
JSON representation
Sandbox Claude Instance without exposing Git
- Host: GitHub
- URL: https://github.com/tnfru/autobox
- Owner: tnfru
- License: mit
- Created: 2025-08-24T17:00:36.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2026-05-22T12:20:56.000Z (about 2 months ago)
- Last Synced: 2026-05-22T17:54:20.420Z (about 2 months ago)
- Language: Shell
- Homepage:
- Size: 141 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# autobox
### Run multiple Claude agents in parallel. Keep your git history safe.
[](https://opensource.org/licenses/MIT)
[](http://makeapullrequest.com)
[](https://www.docker.com/)
[](https://claude.ai/download)
`--dangerously-skip-permissions` without the danger. Each agent runs in its own Docker container on a separate git worktree. Your `.git` is hidden behind a tmpfs — Claude gets full autonomy but can't touch your history, force-push, or delete branches. Spawn agents, attach to any of them, detach, come back later.
https://github.com/user-attachments/assets/565bf780-cf2d-4c16-a1b7-c471733a24de
## Quick Start
```bash
# Install
curl -sSL https://raw.githubusercontent.com/tnfru/autobox/master/install.sh | bash
# Launch the agent manager
autobox agents
```
Type a task, hit Enter. The agent spawns in the background. Select it and press Enter to attach. `Ctrl-Q` to detach — the agent keeps working. Repeat.
```bash
# Or run a single agent directly
autobox -- -p "fix all failing tests"
```
**Requires:** [Docker](https://www.docker.com/) and [Claude Code](https://claude.ai/download)
## How It Works
```
┌──────────────────────────────────────────────────────────┐
│ autobox agents (TUI) │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ fix-auth ● run│ │ add-tests ● run│ ... │
│ │ agent/fix-auth │ │ agent/add-tests │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
└───────────┼────────────────────┼──────────────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Docker container │ │ Docker container │
│ │ │ │
│ Claude Code │ │ Claude Code │
│ --skip-perms │ │ --skip-perms │
│ │ │ │
│ /workspace ──────│──│── git worktree │
│ .git = tmpfs │ │ .git = tmpfs │
└──────────────────┘ └──────────────────┘
```
Each agent gets:
1. **A git worktree** on a new branch — instant checkout, no file copying
2. **A Docker container** with `.git` hidden behind a tmpfs
3. **Full autonomy** — `--dangerously-skip-permissions` with Docker access proxied for safety
4. **Its own session** — conversations persist across attach/detach
When you're done, changes are already on disk. Review the branch, merge or discard.
## Agent Manager
`autobox agents` launches a TUI for managing multiple agents:
| Key | Action |
|-----|--------|
| Type + Enter | Start a new agent with that task |
| ↑/↓ or j/k | Navigate the agent list |
| Enter | Attach to a running agent |
| Ctrl-Q | Detach from agent (container keeps running) |
| Enter | Open completed agent's worktree in Claude (normal permissions) |
| /exit | Return from worktree session to TUI |
| d | Delete an agent (confirms if running or dirty) |
| t | Toggle dark/light theme |
| q | Quit |
Agents are grouped into **Working** (running containers) and **Completed** (finished, with file changes or clean). Desktop notifications fire when an agent finishes.
## What's Protected
| Threat | Protection |
|--------|------------|
| `git push --force` | `.git` hidden behind tmpfs — no remote access |
| `git reset --hard` | No real git history in the container |
| Rewrite commits | No commits to rewrite |
| Delete branches | No branches accessible |
| Exfiltrate code | Optional firewall restricts to Anthropic, GitHub, npm, PyPI |
| Escape via Docker | Socket proxy blocks privileged mode, host namespaces, out-of-workspace mounts |
| Modify files outside project | Container filesystem isolation |
## Installation
```bash
curl -sSL https://raw.githubusercontent.com/tnfru/autobox/master/install.sh | bash
```
Manual install
```bash
git clone https://github.com/tnfru/autobox.git
cd autobox
cp autobox ~/.local/bin/
pip install -e . # for the TUI (autobox agents)
```
From source (development)
```bash
git clone https://github.com/tnfru/autobox.git
cd autobox
uv pip install -e .
cp autobox ~/.local/bin/
```
## Options
| Flag | Description |
|------|-------------|
| `--name NAME` | Name the agent/worktree (default: derived from task) |
| `--worktree PATH` | Re-enter an existing worktree instead of creating one |
| `--detach` | Start container in background (used by TUI) |
| `--firewall` | Restrict outbound traffic to Anthropic, GitHub, npm, PyPI |
| `--no-firewall` | (default) Unrestricted network |
| `--docker` | (default) Mount Docker socket via security proxy |
| `--no-docker` | Don't mount Docker socket |
| `--network NAME` | Connect to a Docker network (e.g. for databases) |
| `--continue` | After container exits, resume session on host with normal permissions |
| `--no-continue` | (default) Drop into worktree shell without resuming |
| `--full` | Include `node_modules`, `.venv` in the worktree |
| `--rebuild` | Force Docker image rebuild |
| `--purge-sessions` | Delete saved session data for the project |
| `-- [args]` | Pass remaining arguments to Claude |
## Standalone Usage
Don't need the TUI? Run a single agent directly:
```bash
# Current directory
autobox
# Specific project
autobox /path/to/project
# Give Claude a task
autobox -- -p "refactor the auth module"
# Resume a previous conversation
autobox -- --resume
# With network firewall
autobox --firewall
# Connect to a local database
autobox --network my-network
```
When the container exits, you land in the worktree to review changes.
## How It Compares
| | autobox | Bare `--dangerously-skip-permissions` | Process sandboxes |
|---|---------|---------------------------------------|-------------------|
| **Git safety** | `.git` hidden behind tmpfs | `.git` fully writable | `.git` writable |
| **Parallel agents** | TUI manages multiple agents | Manual terminal juggling | N/A |
| **Network control** | Firewall allowlist | Unrestricted | Varies |
| **Blast radius** | Container only | Entire system | Project directory |
| **Session continuity** | Attach/detach, persists | N/A | Native |
## Architecture
```
autobox (bash) Entry point — arg parsing, worktree, Docker orchestration
autobox agents (Python/TUI) Agent manager — spawn, attach, detach, cleanup
devcontainer/
Dockerfile debian:bookworm-slim + native Claude binary (~591MB)
entrypoint.sh Firewall init + throwaway git init on tmpfs
init-firewall.sh iptables/ipset rules for allowlisted domains
docker-proxy.py Docker socket proxy — blocks privileged containers, restricts mounts
```
## FAQ
Why not just use Anthropic's devcontainer?
The official devcontainer mounts your full project directory including `.git`. autobox exists specifically to prevent that — your git history never enters the container.
Does this limit what Claude can do?
No. Claude has full `--dangerously-skip-permissions` inside the container. It can edit files, run commands, install packages — it just can't touch your git history or escape the container.
What about Docker-in-Docker?
By default, the host Docker socket is mounted so Claude can spin up sibling containers. A proxy (`docker-proxy.py`) sits between Claude's Docker CLI and the real daemon, blocking privileged mode, host PID namespace, `SYS_ADMIN` capabilities, device mounts, and bind mounts outside the workspace. Pass `--no-docker` to disable the socket mount entirely.
What about .env files?
The worktree only contains git-tracked files. Untracked files like `.env` won't be present unless you add them manually. Use `--full` to copy dependency directories.
What does the firewall allow?
Anthropic API, GitHub (IPs from their `/meta` endpoint), npm, PyPI, and Sentry/Statsig (Claude telemetry). Everything else is blocked via `iptables`. IPv6 is rejected entirely.
How do I clean up worktrees?
The TUI handles cleanup automatically. For manual cleanup:
```bash
git worktree list # see all worktrees
git worktree remove .claude/worktrees/NAME # remove one
```
## Contributing
PRs welcome. See [CLAUDE.md](CLAUDE.md) for development notes.
## License
[MIT](https://opensource.org/licenses/MIT)