vvbox 0.1.0

Lightweight sandbox runner for macOS 26 using Apple container CLI.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# 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)

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

## Quick start

```bash
# 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`:

```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`