Nebubox — AI Coding Tools, Safely Contained

Key Features

Multi-tool support — Claude Code, Antigravity CLI, Codex CLI, and GitHub Copilot CLI out of the box
Filesystem isolation — only the mounted project directory is accessible
Auth persistence — credentials survive across container restarts via shared host directories
Zero runtime dependencies — just Node.js and Docker
Non-root containers — runs as coder user (UID 1000) with passwordless sudo
Playwright support — optional --playwright flag installs headless browser system dependencies, global CLIs, and configures a persistent host cache

Architecture

Nebubox Architecture

Nebubox mounts your project directory only — the rest of the host filesystem stays invisible.

Supported Tools

Tool	Launch command inside container
Claude Code	`claude --dangerously-skip-permissions`
Antigravity CLI	`agy --dangerously-skip-permissions`
Codex CLI	`codex --dangerously-bypass-approvals-and-sandbox`
GitHub Copilot CLI	`copilot --yolo`

When --tool is omitted, Nebubox presents an interactive prompt to select a tool.

Quick Start

# Start a container (interactive tool selection)
nebubox start ./my-project

# Start with a specific tool
nebubox start ./my-project --tool claude
nebubox start ./my-project --tool antigravity
nebubox start ./my-project --tool codex
nebubox start ./my-project --tool copilot

# Start with GitHub CLI support
nebubox start ./my-project --tool claude --github

This will:

Build the Docker image for the tool (first time only)
Create and start a container with your project mounted at /home/coder/workspace
Drop you into an interactive bash shell inside the container
Print a hint for how to launch the AI tool

When you exit the shell, the container keeps running. Reconnect anytime with nebubox attach.

How It Works

Each tool has a profile that defines its install method, auth directory, and environment. Nebubox dynamically generates a Dockerfile from the profile, builds an image, and creates containers with bind mounts:

Project — <your-project> → /home/coder/workspace
Auth — ~/.nebubox/auth/<tool>/ → tool’s config directory in the container

Containers are named nebubox-<tool>-<project-dir> (or nebubox-<tool>-<project-dir>-github when --github is used) and labeled for easy filtering.

Directory Layout on Host

~/.nebubox/
  auth/
    claude/         # Claude Code credentials & config
    antigravity/    # Antigravity CLI credentials (shared)
    codex/          # Codex CLI credentials
    copilot/        # GitHub Copilot CLI credentials (~/.copilot)
    github/         # GitHub CLI auth + .gitconfig (when --github is used)
  playwright-cache/ # Playwright browser cache (when --playwright is used)

Note for GitHub Copilot CLI: On first login, select “Yes, store in plain text” when prompted about the system vault. Storing credentials in ~/.copilot/config.json allows them to persist safely in ~/.nebubox/auth/copilot/ across container runs.

GitHub CLI Integration

Pass --github to install GitHub CLI in the container with persistent credentials. After a one-time gh auth login, your git identity is automatically configured from your GitHub account, and AI tools can create PRs, push branches, and call the GitHub API from inside the sandbox.

See the Advanced section in the README for the full setup guide.

Playwright Integration

Pass --playwright to equip the container with headless browser screenshot and testing capabilities out-of-the-box. Nebubox installs system packages for Chromium rendering (including international fonts and unzip) and installs Playwright executables globally.

The first time you start a container with --playwright, you should download the Chromium browser binary into the persistent host cache:

playwright install chromium

Once installed, you can test it by running:

playwright screenshot https://example.com example.png