vibebox

A minimal CLI for running dev sandboxes and CLI agents in Docker containers.

Each workspace gets its own isolated container with automatic credential sync and config isolation. The architecture supports multiple agents. Currently only Claude Code is integrated.

Also good to protect your butt from npm supply chain attacks.

Why vibebox instead of docker sandbox, raw docker, or devcontainers?

Requirements

• Docker Desktop
• Agent CLI on host (optional - enables shared auth/config across workspaces)

Install

npm install -g vibebox

Add to your shell profile (optional):

alias claude="vibebox agent run claude"

Usage

# Agent commands
vibebox agent run <name> [args]   # Run agent in sandbox
vibebox agent run claude --temp   # Temporary workspace, prompts to save on exit
vibebox agent ls                  # List agents with install status
vibebox agent install <name>      # Install agent in sandbox

# Container commands
vibebox enter             # Shell into sandbox
vibebox exec <cmd>        # Run command in sandbox
vibebox ls                # List sandboxes
vibebox stop [--all]      # Stop sandbox(es)
vibebox rm [--all]        # Remove sandbox(es)
vibebox rebuild           # Rebuild image with current host config

# Customization (experimental)
vibebox customize setup global   # Edit ~/.vibebox/setup.sh (runs in all sandboxes)
vibebox customize setup local    # Edit vibebox.setup.sh (runs in this project)
vibebox customize image global   # Edit ~/.vibebox/Dockerfile (custom base image)
vibebox customize image local    # Edit vibebox.Dockerfile (custom project-specific image)

Temporary Workspaces

vibebox agent run claude --temp

Creates a workspace in your system's temp directory. On exit, prompts to save or delete:

• Yes: Copy to destination (default: ~/claude-session-<timestamp>)
• No: Delete

Port Management

Default ports exposed: 5173, 3000, 3001, 4173, 8080 (dynamic host allocation)

vibebox ports ls           # Show current port mappings
vibebox ports add 4200     # Add custom port
vibebox ports rm 3000      # Remove port

When a service starts listening inside the container, you'll see:

● Port 5173 → http://localhost:32770

For unmapped ports:

⊖ Port 9000 listening (not exposed)

Image Build

The Docker image matches your host environment. vibebox rebuild detects your Node.js/npm versions and user info (UID, GID, home path), ensuring seamless file permissions.

Version Management

When agent versions differ between host and sandbox:

claude version mismatch! Host: 2.1.2, Sandbox: 2.1.0

Choose update strategy:
  [1] Sync to higher version (2.1.2)
  [2] Update both to latest
  [N] Cancel

Git & SSH Integration (experimental)

Git config is automatically synced from host (user.name, user.email, aliases, common settings).

SSH agent forwarding and GitHub CLI are disabled by default for security (prevents prompt injection from using your credentials). Enable in vibebox.config.json:

{
  "sshAgent": true,
  "ghAuth": true
}

When enabled:

• SSH agent: Forwarded to container. Keys never leave the host. Works with Docker Desktop (macOS) and native Docker (Linux).
• GitHub CLI: ~/.config/gh/hosts.yml mounted read-only, gh auth setup-git runs automatically.

HTTPS hint: If using HTTPS remotes with SSH available, you'll see:

[vibebox] SSH auth available. To use SSH for git:
          git remote set-url origin [email protected]:user/repo.git

Customization (experimental)

Setup scripts run once when a container is first created:

• ~/.vibebox/setup.sh - Global, runs in all sandboxes
• vibebox.setup.sh - Local, runs in this project sandbox only

Custom Dockerfiles extend the base image:

• ~/.vibebox/Dockerfile - Global customizations (FROM vibebox)
• vibebox.Dockerfile - Project-specific (FROM vibebox:user or FROM vibebox)

Config is stored in vibebox.config.json at project root and ~/.vibebox/config.json globally. Local overrides global.

{
  "ports": ["3000", "5173"],
  "sudo": false,
  "sshAgent": false,
  "ghAuth": false
}

| Option | Default | Description | |--------|---------|-------------| | ports | ["3000", "3001", ...] | Ports to expose from sandbox | | sudo | false | Enable sudo access in sandbox | | sshAgent | false | Forward SSH agent to sandbox | | ghAuth | false | Mount GitHub CLI credentials |

All vibebox.* files at project root are meant to be git-tracked. The .vibebox/ folder contains only runtime artifacts and can be gitignored.

Image hierarchy: vibebox → vibebox:user (global) → vibebox:<hash> (local)

Run vibebox rebuild after editing Dockerfiles.

Why vibebox?

vs docker sandbox: Docker Desktop's sandbox uses microVM isolation—stronger security, but a blackbox. No credential sync (re-auth every session), no customization, runs in full yolo mode. On Linux it falls back to container isolation anyway. vibebox trades some isolation for continuity: credentials sync, config persists, you can customize and debug.

vs raw docker: No Dockerfiles, no mount flags, no manual credential copying. Just vibebox agent run claude. Container user matches your UID/GID so file permissions work. Port mappings shown automatically when services start.

vs devcontainers: No VS Code dependency, no devcontainer.json. Built for CLI agents, not general dev environments.

License

AGPL-3.0-or-later