@@ -5,7 +5,7 @@
55 </picture>
66 </a>
77</p>
8−<p align="center">Your ultrafast open source AI sandbox.</p>
8+<p align="center">an ultrafast, open-source sandbox for running coding agents safely.</p>
99
1010<p align="center">
1111 <a href="https://crates.io/crates/vibebox">
@@ -24,45 +24,77 @@
2424 <a href="README.zh.md">简体中文</a>
2525</p>
2626
27−**VibeBox is a per-project micro-VM sandbox for coding agents on macOS (Apple Virtualization Framework), fast to enter,
28−configurable, and built around sessions.**
27+**VibeBox is a per-project micro-VM sandbox for running coding agents on macOS (Apple Virtualization Framework).**
28+It’s optimized for a *daily-driver* workflow: fast warm re-entry, explicit mounts, and reusable sessions.
2929
30−- **Enter in seconds:** `vibebox` drops you into a reusable sandbox for the current repo
31−- **Project-scoped:** explicit mounts + repo-contained changes
32−- **Sessioned:** multi-instance + session management (reuse, multiple terminals, cleanup)
30+**Who it’s for:** macOS users running coding agents who want real isolation without giving up a fast daily workflow.
31+
32+**Quick facts:** warm re-entry is typically **<5s** on my M3 (varies by machine/cache); first run downloads and
33+provisions a Debian base image (network dependent).
34+
35+**Security model:** Linux guest VM with explicit mount allowlists from `vibebox.toml` (repo-first, everything else
36+opt-in).
37+
38+- **enter/attach in seconds:** `vibebox` drops you into a reusable sandbox for the current repo
39+- **project-scoped by default:** explicit mounts + repo-contained changes (repo-first, everything else is allowlisted)
40+- **sessioned:** multi-instance + session management (reuse, multiple terminals, cleanup)
3341
3442### Quick Demo
3543
3644```bash
37−# 1) from any repo
45+# from any repo
3846cd my-project
3947vibebox
4048```
4149
50+What you should see (roughly):
51+
52+```text
53+vibebox: starting (session: my-project)
54+vibebox: attaching...
55+vibecoder@vibebox:~/my-project$
56+```
57+
4258[](https://vibebox.robcholz.com)
4359
4460---
4561
4662### Why I built VibeBox
4763
48−I use agents like Codex and CC a lot, but I always felt uneasy running them directly on my host machine. If I lock
49−things
50−down, I get interrupted by constant “are you sure?” prompts. If I loosen it up, I worry the agent might touch the
51−wrong files or run something I didn’t intend.
64+I use coding agents daily, and I wanted to give them a real shell without handing them my host machine.
65+Lock things down and you get nonstop confirmations; loosen it up and you worry about deleting files, touching secrets,
66+or wandering outside the repo.
5267
53−I wanted something that feels as frictionless as giving an agent a real shell, but with a hard isolation boundary. So I
54−built VibeBox: a per-project micro-VM sandbox that starts fast, keeps changes contained to the repo, and lets me iterate
55−without babysitting permissions.
68+VibeBox is the middle ground: a per-repo sandbox with a hard VM boundary, fast re-entry, and explicit mounts. It’s built
69+to be “always on” for agent work without turning safety into a chore.
70+
71+### Why a micro-VM (vs containers)?
72+
73+Containers are great. VibeBox isn’t trying to replace Docker/devcontainers for building services.
74+
75+I specifically wanted a VM-shaped default for agent workflows on macOS:
76+
77+- **guest-kernel isolation boundary by default:** when I’m letting an agent run arbitrary commands, I want “safe mode”
78+ to
79+ be a Linux guest, not my host.
80+- **sessions as a first-class workflow:** attach/reuse per repo, multiple terminals into the same sandbox, reliable
81+ cleanup to avoid orphan environments.
82+- **explicit mount allowlists as the primary UX:** repo-scoped by default; anything else is an explicit decision.
83+- **minimal per-repo setup:** you *can* reproduce parts of this with compose/devcontainers, but I wanted a single
84+ command
85+ that works repo-to-repo without maintaining container configs for the basic “safe shell” workflow.
5686
5787### Comparison
5888
5989Here’s why I didn’t just use existing options:
6090
61−- **vibe**: super convenient, but it’s too minimal for what I need. It lacks basic configuration, and it doesn’t give me
62− the multi-instance + session management my workflow wants.
91+- **vibe**: super convenient and nails “zero-config, just go”. VibeBox is intentionally on a different axis: per-repo
92+ config + sessions + multi-instance lifecycle.
6393- **QEMU**: powerful, but the configuration surface area is huge. For day-to-day sandboxing it’s not “open a repo and
6494 go” — it’s a project on its own.
65−- **Docker / devcontainers**: great ecosystem, but for daily use it feels heavy.
95+- **Docker / devcontainers / devpods**: great ecosystem. My friction wasn’t raw startup time, it was the day-to-day
96+ overhead of keeping per-repo agent sandboxes *safe-by-default* (mount allowlists, secrets exposure, attach/reuse,
97+ cleanup) without maintaining container configs per repo for the basic workflow.
6698
6799That’s what pushed me to build **VibeBox**: I wanted a per-project sandbox that’s fast to enter (just `vibebox`),
68100supports real configuration + sessions, and keeps a hard isolation boundary.
@@ -70,13 +102,13 @@ supports real configuration + sessions, and keeps a hard isolation boundary.
70102### Installation
71103
72104```bash
73−# YOLO
105+# install script
74106curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash
75107
76−# Package managers
108+# package managers
77109cargo install vibebox
78110
79−# Or manually
111+# manual install
80112curl -LO https://github.com/robcholz/vibebox/releases/download/latest/vibebox-macos-arm64.zip
81113unzip vibebox-macos-arm64.zip
82114mkdir -p ~/.local/bin
@@ -86,7 +118,7 @@ export PATH="$HOME/.local/bin:$PATH"
86118
87119**Requirements**
88120
89−- macOS on Apple Silicon (Vibebox uses Apple's virtualization APIs).
121+- macOS on Apple Silicon (VibeBox uses Apple's virtualization APIs).
90122
91123**First Run**
92124
@@ -102,7 +134,7 @@ cd /path/to/your/project
102134vibebox
103135```
104136
105−On first run, Vibebox creates `vibebox.toml` in your project (if missing) and a `.vibebox/` directory for instance data.
137+On first run, VibeBox creates `vibebox.toml` in your project (if missing) and a `.vibebox/` directory for instance data.
106138
107139**Configuration (`vibebox.toml`)**
108140
@@ -153,7 +185,7 @@ vibebox explain # show mounts and network info
153185- Default SSH user: `vibecoder`
154186- Hostname: `vibebox`
155187- Base image provisioning installs: build tools, `git`, `curl`, `ripgrep`, `openssh-server`, and `sudo`.
156−- On first login, Vibebox installs `mise` and configures tools like `uv`, `node`, `@openai/codex`, and
188+- On first login, VibeBox installs `mise` and configures tools like `uv`, `node`, `@openai/codex`, and
157189 `@anthropic-ai/claude-code` (best-effort).
158190- Shell aliases: `:help` and `:exit`.
159191
@@ -168,27 +200,24 @@ vibebox explain # show mounts and network info
168200If you're interested in contributing to VibeBox, please read our [contributing docs](CONTRIBUTING.md) before
169201submitting a pull request.
170202
171−### Using VibeBox
172−
173−Feel free to use
174−
175203### FAQ
176204
177−#### How is this different from other Sandboxes?
205+#### How is this different from other sandboxes?
178206
179−Vibebox is built for fast, repeatable local sandboxes with minimal ceremony. What’s different here:
207+VibeBox is built for fast, repeatable local sandboxes with minimal ceremony. What’s different here:
180208
181−- Warm startup is typically under **6 seconds** on my M3, so you can jump back in quickly.
209+- Warm re-entry is typically **<5s** on my M3 (varies by machine/cache), so you can jump back in quickly.
182210- One simple command — `vibebox` — drops you into the sandbox from your project.
183211- Configuration lives in `vibebox.toml`, where you can set CPU, RAM, disk size, and mounts.
212+- Sessions are first-class: reuse, multiple terminals, cleanup.
184213
185−### Special Thank
214+### Special thanks
186215
187216[vibe](https://github.com/lynaghk/vibe) by lynaghk.
188217
189−And amazing Rust community, without your rich crates and fantastic toolchain like [crates.io](https://crates.io), this
190−wouldn't be possible!
218+And the amazing Rust community — without the ecosystem and toolchain like [crates.io](https://crates.io), this wouldn't
219+be possible!
191220
192221---
193222
194−**Follow me on X** [X.com](https://x.com/robcholz)
223+**Follow me on X** [x.com/robcholz](https://x.com/robcholz)