VibeBox

The Vibebox TUI (Terminal User Interface) provides a visual dashboard for managing micro-VMs. Upon starting, the interface displays a non-fixed welcome header that includes:

• A welcome message with the current Vibebox version.
• An ASCII banner.
• An outlined information box containing:
  • The current working directory.
  • The current VM version.
  • Resource limits (maximum memory and CPU cores).

Because the header position is flexible, it will move upwards as the VM terminal history grows. Following the header, the TUI prints a list of all available Vibebox commands along with their descriptions before transitioning into a normal terminal session.

VibeBox uses a folder-based session management system. Each session is represented by a unique folder.

Key behaviors:

• Auto-shutdown: By default, VibeBox tracks a reference count for each VM. If the reference count reaches 0, the VM will automatically shut down after the duration specified by DEFAULT_EXPECT_TIMEOUT.
• Preventing Auto-shutdown: You can execute specific commands within a session to prevent it from automatically shutting down.
• Resuming Sessions: You can use commands to resume an existing session.

VibeBox manages data in three distinct locations:

1. Project State (.vibebox/): Located in your project root. Stores the instance disk, SSH keys, logs, and manager socket/pid. Use vibebox reset to clear this.
2. Session Index (~/.vibebox/sessions): A global index of project sessions, viewable via vibebox list.
3. Global Cache (~/.cache/vibebox): Stores the Debian base image and shared guest cache. Use vibebox purge-cache to clear this.

Vibebox uses two distinct command namespaces depending on whether you are interacting with the host or the guest VM:

1. Vibebox Commands: Used on the host CLI to manage the Vibebox environment. These follow the format :<command> (e.g., :exit).
2. Box Commands: Used inside the spawned VM. These are standard Linux commands and follow the typical Linux format (e.g., ls, cd).

VibeBox manages a Linux VM (Debian-based) on Apple Silicon macOS using the Apple Virtualization framework. The lifecycle follows these stages:

1. Image Acquisition: On the first run, VibeBox downloads a Debian base image and verifies its integrity using SHA-512.
2. Provisioning: The base image is decompressed and provisioned once to create a default template.
3. Instance Creation: A per-project instance disk is created at .vibe/instance.raw.
4. Persistence: Instance disks persist across multiple runs. To start fresh, you must manually delete the .vibe/instance.raw file.
5. Execution: The VM boots, auto-logs in as root, and streams the console to your terminal in raw mode for interactive use.

Vibebox distributes data across global and project-specific locations:

Warning: Deleting the [project_dir]/.vibebox/ directory permanently deletes the session. The global index entry will be cleaned up automatically by commands that fail to locate the directory.

To use VibeBox, your environment must meet the following requirements:

• Hardware: ARM-based macOS (Apple Silicon).
• OS: macOS Ventura or newer.
• Network: The first run requires internet access to download and verify the Debian base image.
• Permissions: The binary requires the com.apple.security.virtualization entitlement. VibeBox will attempt to self-sign the binary if this entitlement is missing upon startup.

Sessions represent underlying VM instances identified by a UUIDv7. You can manage them using the following host commands:

• Connect or Create: Run vibebox without a configuration file to connect to an existing session or create a new one if none exists for that directory.
• List Sessions: Use vibebox list to see all active/known sessions.
• Delete Session: Use vibebox delete <session_id> to permanently remove a session. This removes the [session.directory]/.vibebox/ directory and the global index entry.

# Connect to or create a session
vibebox

# List all sessions
vibebox list

# Delete a specific session
vibebox delete 019bf290-cccc-7c23-ba1d-dce7e6d40693

VibeBox requires Apple Silicon macOS (it uses the Apple Virtualization Framework). You can install it using one of the following methods:

YOLO: One-click install

curl -fsSL https://raw.githubusercontent.com/robcholz/vibebox/main/install | bash

Using Cargo

cargo install vibebox

Manual Install

1. Download the latest macOS arm64 zip from GitHub releases.
2. Unzip and move the binary to your local bin directory.
3. Add the directory to your PATH.

curl -LO https://github.com/robcholz/vibebox/releases/download/latest/vibebox-macos-arm64.zip
unzip vibebox-macos-arm64.zip
mkdir -p ~/.local/bin
mv vibebox ~/.local/bin
export PATH="$HOME/.local/bin:$PATH"

You can use the explain command to display all active mounts, network activity, and visibility settings for a session.

To manage these settings:

• Disable Network: You can set a connection to disable to turn off a specific network connection.
• Configuration: Network and mount configurations can be managed using a configuration file located at .vibebox/config.toml.