mirror of
https://github.com/robcholz/vibebox.git
synced 2026-04-21 03:16:35 +02:00
robcholz
159 lines
4.8 KiB
Markdown
159 lines
4.8 KiB
Markdown
<p align="center">
|
||
<a href="https://vibebox.robcholz.com">
|
||
<picture>
|
||
<img src="docs/banner.png" alt="VibeBox logo">
|
||
</picture>
|
||
</a>
|
||
</p>
|
||
<p align="center">Your ultrafast open source AI sandbox.</p>
|
||
|
||
<p align="center">
|
||
<a href="https://crates.io/crates/vibebox">
|
||
<img alt="Crates.io" src="https://img.shields.io/crates/v/vibebox.svg">
|
||
</a>
|
||
<a href="https://github.com/robcholz/vibebox/blob/main/LICENSE">
|
||
<img alt="MIT licensed" src="https://img.shields.io/badge/license-MIT-blue.svg">
|
||
</a>
|
||
<a href="https://github.com/robcholz/vibebox/actions?query=workflow%3ACI+branch%3Amain">
|
||
<img alt="Build Status" src="https://github.com/robcholz/vibebox/workflows/CI/badge.svg">
|
||
</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="README.md">English</a> |
|
||
<a href="README.zh.md">简体中文</a>
|
||
</p>
|
||
|
||
[](https://vibebox.robcholz.com)
|
||
|
||
---
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# YOLO
|
||
curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash
|
||
|
||
# Package managers
|
||
cargo install vibebox
|
||
|
||
# Or manually (bad)
|
||
curl -LO https://github.com/robcholz/vibebox/releases/download/latest/vibebox-macos-arm64.zip
|
||
unzip vibebox-macos-arm64.zip
|
||
mkdir -p ~/.local/bin
|
||
mv vibe ~/.local/bin
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
```
|
||
|
||
> [!TIP]
|
||
> We truly recommend you to use `YOLO` to install.
|
||
|
||
**Requirements**
|
||
|
||
- macOS on Apple Silicon (Vibebox uses Apple's virtualization APIs).
|
||
|
||
**First Run**
|
||
|
||
The first `vibebox` run downloads a Debian base image and provisions it. After that, per-project instances reuse the
|
||
cached base image for much faster startups.
|
||
|
||
### Documentation
|
||
|
||
**Quick Start**
|
||
|
||
```bash
|
||
cd /path/to/your/project
|
||
vibebox
|
||
```
|
||
|
||
On first run, Vibebox creates `vibebox.toml` in your project (if missing) and a `.vibebox/` directory for instance data.
|
||
|
||
**Configuration (`vibebox.toml`)**
|
||
|
||
`vibebox.toml` lives in your project root by default. You can override it with `vibebox -c path/to/vibebox.toml` or the
|
||
`VIBEBOX_CONFIG_PATH` env var, but the path must stay inside the project directory.
|
||
|
||
Default config (auto-created when missing):
|
||
|
||
```toml
|
||
[box]
|
||
cpu_count = 2
|
||
ram_mb = 2048
|
||
disk_gb = 5
|
||
mounts = [
|
||
"~/.codex:~/.codex:read-write",
|
||
"~/.claude:~/.claude:read-write",
|
||
]
|
||
|
||
[supervisor]
|
||
auto_shutdown_ms = 20000
|
||
```
|
||
|
||
`disk_gb` is only applied when the instance disk is first created. If you change it later, run `vibebox reset` to
|
||
recreate the disk.
|
||
|
||
**Mounts**
|
||
|
||
- Your project is mounted read-write at `~/<project-name>`, and the shell starts there.
|
||
- If a `.git` directory exists, it is masked with a tmpfs mount inside the VM to discourage accidental edits from the
|
||
guest.
|
||
- Extra mounts come from `box.mounts` with the format `host:guest[:read-only|read-write]`.
|
||
- Host paths support `~` expansion. Relative guest paths are treated as `/root/<path>`.
|
||
- Guest paths that use `~` are linked into `/home/<ssh-user>` for convenience. Run `vibebox explain` to see the resolved
|
||
host/guest mappings.
|
||
|
||
**CLI Commands**
|
||
|
||
```bash
|
||
vibebox # start or attach to the current project VM
|
||
vibebox list # list known project sessions
|
||
vibebox reset # delete .vibebox for this project and recreate on next run
|
||
vibebox purge-cache # delete the global cache (~/.cache/vibebox)
|
||
vibebox explain # show mounts and network info
|
||
```
|
||
|
||
**Inside the VM**
|
||
|
||
- Default SSH user: `vibecoder`
|
||
- Hostname: `vibebox`
|
||
- Base image provisioning installs: build tools, `git`, `curl`, `ripgrep`, `openssh-server`, and `sudo`.
|
||
- On first login, Vibebox installs `mise` and configures tools like `uv`, `node`, `@openai/codex`, and
|
||
`@anthropic-ai/claude-code` (best-effort).
|
||
- Shell aliases: `:help` and `:exit`.
|
||
|
||
**State & Cache**
|
||
|
||
- Project state lives in `.vibebox/` (instance disk, SSH keys, logs, manager socket/pid). `vibebox reset` removes it.
|
||
- Global cache lives in `~/.cache/vibebox` (base image + shared guest cache). `vibebox purge-cache` clears it.
|
||
- Session index lives in `~/.vibebox/sessions` and is shown by `vibebox list`.
|
||
|
||
### Contributing
|
||
|
||
If you're interested in contributing to VibeBox, please read our [contributing docs](CONTRIBUTING.md) before
|
||
submitting a pull request.
|
||
|
||
### Using VibeBox
|
||
|
||
Feel free to use, but remember to promote VibeBox as well!
|
||
|
||
### FAQ
|
||
|
||
#### How is this different from other Sandboxes?
|
||
|
||
Vibebox is built for fast, repeatable local sandboxes with minimal ceremony. What’s different here:
|
||
|
||
- Warm startup is typically under **6 seconds** on my M3, so you can jump back in quickly.
|
||
- One simple command — `vibebox` — drops you into the sandbox from your project.
|
||
- Configuration lives in `vibebox.toml`, where you can set CPU, RAM, disk size, and mounts.
|
||
|
||
### Special Thank
|
||
|
||
[vibe](https://github.com/lynaghk/vibe) by lynaghk.
|
||
|
||
And amazing Rust community, without your rich crates and fantastic toolchain like [crates.io](https://crates.io), this
|
||
wouldn't be possible!
|
||
|
||
---
|
||
|
||
**Follow me on X** [X.com](https://x.com/robcholz)
|