# Overview
vvbox is a lightweight sandbox runner for macOS 26. It creates a clean snapshot of a git repo, runs commands inside an isolated container, and produces a patch you can review and apply back to the original repo.
## Why it exists
- Keep the main agent or orchestration layer **restricted** (no shell, no writes).
- Run risky tasks in a **separate container VM** with explicit mounts.
- Produce **reviewable patches** instead of touching your repo directly.
- Avoid heavy compose stacks while still supporting simple service dependencies.
## Problems it solves
- **Safe automation:** isolate high‑risk operations in a container.
- **Reproducibility:** pin image + setup commands.
- **Reviewability:** all changes are patches you can accept or reject.
- **Minimal config:** YAML config replaces heavy orchestration.
## How it works
1. **Snapshot**: creates a git worktree snapshot at `~/.vvbox/worktrees/<run-id>`.
2. **Run**: starts a Linux container and mounts the snapshot at `/work`.
3. **Services (optional)**: spins up simple service containers from config.
4. **Patch**: generates `git diff --binary` from the snapshot.
5. **Apply**: you decide when to apply the patch.
## Requirements
- macOS 26 (Apple silicon)
- Apple `container` CLI installed
## Quick start
```bash
vvbox init --repo /path/to/repo
vvbox run --repo /path/to/repo --cmd "sh -lc 'npm test'" --diff
vvbox apply --last
```