vvbox

Experimental project: lightweight sandbox runner for macOS 26.

vvbox creates a git worktree snapshot, runs commands inside an isolated container, and returns a patch you can review and apply. It’s designed for safe automation and minimal orchestration overhead.

Why

• Keep your 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 writing directly to your repo.
• Replace heavyweight compose stacks with a small, readable config.

How it works

1. Snapshot repo into a worktree under ~/.vvbox/worktrees/<run-id>
2. Run the command in a container with the snapshot mounted at /work
3. Optionally start simple service containers from config
4. Generate a patch from the snapshot
5. Apply the patch to your original repo when ready

Requirements

• macOS 26 (Apple silicon)
• Apple container CLI installed

Install (dev)

cd vvbox
cargo build
./target/debug/vvbox --help

Quick start

# Initialize default config
vvbox init --repo /path/to/repo

# Run a task in a sandbox
vvbox run --repo /path/to/repo --cmd "sh -lc 'npm test'" --diff

# Run directly in an existing worktree (no snapshot/patch)
vvbox run --worktree /path/to/worktree --in-place --cmd "sh -lc 'npm test'"

# Review + apply patch
vvbox apply --last

Config

vvbox reads config in this order:

1. ~/.vvbox/config.yaml (or .yml, .json)
2. vvbox.yaml (or .yml, .json) in repo root
3. --config <path> override

Example vvbox.yaml:

image: ubuntu:latest
network: default
workdir: /work
env:
  CI: "1"
ports:
  - "8080:8080"
volumes:
  - source: vvbox:cache
    target: /cache
pre_install:
  - apt-get update
  - apt-get install -y git
run:
  - npm install
  - npm test
services:
  - name: db
    image: postgres:16
    env:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - source: vvbox:pgdata
        target: /var/lib/postgresql/data

Notes:

• pre_install and run execute in one sh -lc shell.
• run can be a string or list of commands.
• vvbox:<name> creates a persistent volume at ~/.vvbox/volumes/<name>.

CLI highlights

• vvbox run — run a sandboxed task (use --diff to generate a patch)
• vvbox apply — apply patch (asks for confirmation; use --yes to skip)
• vvbox attach — attach to a kept container (--keep)
• vvbox logs — view run logs
• vvbox services up/down/status/logs — manage simple service containers
• vvbox up / vvbox down — shortcuts for services

Security model

• The main agent stays restricted.
• vvbox runs tasks in a separate container VM with explicit mounts.
• Changes are returned as patches for review.

Troubleshooting

• If the container system isn’t running, vvbox calls container system start automatically.
• If an image lacks /bin/sh, use --cmd with the correct shell or -- <args...>.
• vvbox apply requires a clean tree unless you pass --allow-dirty.

Docs

See the full docs in docs/:

• docs/overview.md
• docs/config.md
• docs/cli.md
• docs/security.md
• docs/troubleshooting.md