@@ -5,7 +5,7 @@
55 </picture>
66 </a>
77</p>
8−<p align="center">The open source AI coding agent.</p>
8+<p align="center">Your ultrafast open source AI sandbox.</p>
99
1010[![Crates.io][crates-badge]][crates-url]
1111[![MIT licensed][mit-badge]][mit-url]
@@ -40,16 +40,96 @@ curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bas
4040
4141# Package managers
4242cargo install vibebox
43+
44+# Or manually (bad)
45+curl -LO https://github.com/robcholz/vibebox/releases/download/latest/vibebox-macos-arm64.zip
46+unzip vibebox-macos-arm64.zip
47+mkdir -p ~/.local/bin
48+mv vibe ~/.local/bin
49+export PATH="$HOME/.local/bin:$PATH"
4350```
4451
4552> [!TIP]
46−> We truly recommend you to use `YOLO`.
53+> We truly recommend you to use `YOLO` to install.
54+
55+**Requirements**
56+
57+- macOS on Apple Silicon (Vibebox uses Apple's virtualization APIs).
58+
59+**First Run**
4760
48−todo
61+The first `vibebox` run downloads a Debian base image and provisions it. After that, per-project instances reuse the
62+cached base image for much faster startups.
4963
5064### Documentation
5165
52−todo
66+**Quick Start**
67+
68+```bash
69+cd /path/to/your/project
70+vibebox
71+```
72+
73+On first run, Vibebox creates `vibebox.toml` in your project (if missing) and a `.vibebox/` directory for instance data.
74+
75+**Configuration (`vibebox.toml`)**
76+
77+`vibebox.toml` lives in your project root by default. You can override it with `vibebox -c path/to/vibebox.toml` or the
78+`VIBEBOX_CONFIG_PATH` env var, but the path must stay inside the project directory.
79+
80+Default config (auto-created when missing):
81+
82+```toml
83+[box]
84+cpu_count = 2
85+ram_mb = 2048
86+disk_gb = 5
87+mounts = [
88+ "~/.codex:~/.codex:read-write",
89+ "~/.claude:~/.claude:read-write",
90+]
91+
92+[supervisor]
93+auto_shutdown_ms = 20000
94+```
95+
96+`disk_gb` is only applied when the instance disk is first created. If you change it later, run `vibebox reset` to
97+recreate the disk.
98+
99+**Mounts**
100+
101+- Your project is mounted read-write at `/usr/local/vibebox-mounts/<project-name>`, and the shell starts there.
102+- If a `.git` directory exists, it is masked with a tmpfs mount inside the VM to discourage accidental edits from the
103+ guest.
104+- Extra mounts come from `box.mounts` with the format `host:guest[:read-only|read-write]`.
105+- Host paths support `~` expansion. Relative guest paths are treated as `/root/<path>`.
106+- Guest paths that use `~` are linked into `/home/<ssh-user>` for convenience. Run `vibebox explain` to see the resolved
107+ host/guest mappings.
108+
109+**CLI Commands**
110+
111+```bash
112+vibebox # start or attach to the current project VM
113+vibebox list # list known project sessions
114+vibebox reset # delete .vibebox for this project and recreate on next run
115+vibebox purge-cache # delete the global cache (~/.cache/vibebox)
116+vibebox explain # show mounts and network info
117+```
118+
119+**Inside the VM**
120+
121+- Default SSH user: `vibecoder`
122+- Hostname: `vibebox`
123+- Base image provisioning installs: build tools, `git`, `curl`, `ripgrep`, `openssh-server`, and `sudo`.
124+- On first login, Vibebox installs `mise` and configures tools like `uv`, `node`, `@openai/codex`, and
125+ `@anthropic-ai/claude-code` (best-effort).
126+- Shell aliases: `:help` and `:exit`.
127+
128+**State & Cache**
129+
130+- Project state lives in `.vibebox/` (instance disk, SSH keys, logs, manager socket/pid). `vibebox reset` removes it.
131+- Global cache lives in `~/.cache/vibebox` (base image + shared guest cache). `vibebox purge-cache` clears it.
132+- Session index lives in `~/.vibebox/sessions` and is shown by `vibebox list`.
53133
54134### Contributing
55135