vibebox

Quick Demo

What you should see (roughly):

Why I built VibeBox

I use coding agents daily, and I wanted to give them a real shell without handing them my host machine. Lock things down and you get nonstop confirmations; loosen it up and you worry about deleting files, touching secrets, or wandering outside the repo.

VibeBox is the middle ground: a per-repo sandbox with a hard VM boundary, fast re-entry, and explicit mounts. It’s built to be “always on” for agent work without turning safety into a chore.

Why a micro-VM (vs containers)?

Containers are great. VibeBox isn’t trying to replace Docker/devcontainers for building services.

I specifically wanted a VM-shaped default for agent workflows on macOS:

• guest-kernel isolation boundary by default: when I’m letting an agent run arbitrary commands, I want “safe mode” to be a Linux guest, not my host.
• sessions as a first-class workflow: attach/reuse per repo, multiple terminals into the same sandbox, reliable cleanup to avoid orphan environments.
• explicit mount allowlists as the primary UX: repo-scoped by default; anything else is an explicit decision.
• minimal per-repo setup: you can reproduce parts of this with compose/devcontainers, but I wanted a single command that works repo-to-repo without maintaining container configs for the basic “safe shell” workflow.

Comparison

Here’s why I didn’t just use existing options:

• vibe: super convenient and nails “zero-config, just go”. VibeBox is intentionally on a different axis: per-repo config + sessions + multi-instance lifecycle.
• QEMU: powerful, but the configuration surface area is huge. For day-to-day sandboxing it’s not “open a repo and go” — it’s a project on its own.
• Docker / devcontainers / devpods: great ecosystem. My friction wasn’t raw startup time, it was the day-to-day overhead of keeping per-repo agent sandboxes safe-by-default (mount allowlists, secrets exposure, attach/reuse, cleanup) without maintaining container configs per repo for the basic workflow.

That’s what pushed me to build VibeBox: I wanted a per-project sandbox that’s fast to enter (just vibebox), supports real configuration + sessions, and keeps a hard isolation boundary.

Installation

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

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

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

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 before submitting a pull request.

FAQ

How is this different from other sandboxes?

VibeBox is built for fast, repeatable local sandboxes with minimal ceremony. What’s different here:

• Warm re-entry is typically <5s on my M3 (varies by machine/cache), 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.
• Sessions are first-class: reuse, multiple terminals, cleanup.

Special thanks

vibe by lynaghk.

And the amazing Rust community — without the ecosystem and toolchain like crates.io, this wouldn't be possible!

Follow me on X x.com/robcholz