Blackhole

English · 中文

Run Claude Code inside an isolated Colima VM container on macOS — exposing only the current project directory while keeping virtiofs live sync, persistent login volumes, and clipboard image paste.

Background

Running claude directly on a macOS host exposes two things at once: your local filesystem (~/.ssh, cloud credentials, Docker sockets, sibling repositories) and your host environment fingerprint (macOS hardware identifiers, locale/timezone settings, host username, environment variables, and direct network interfaces if a proxy drops).

Blackhole replaces the host claude command with a pure Bash launcher (~/.local/bin/claude -> bin/blackhole). Claude Code is never installed on your macOS host — the actual @anthropic-ai/claude-code package lives exclusively inside the Colima VM's Docker image. When you type claude in a project directory, the host symlink intercepts the command and starts an ephemeral Linux container inside your Colima VM so Claude Code only ever sees a generic Linux environment and controlled network egress:

• Directory-scoped mount: Only $PWD is mounted at /workspace over Colima's virtiofs. Host $HOME, SSH agents, and Docker sockets are never mounted.
• Host fingerprint isolation: Runs inside a clean Debian container with --hostname blackhole, a remapped node user matching /workspace UID/GID, and a strict environment variable allowlist (TERM, COLORTERM, NO_COLOR, and optional API keys) — hiding macOS host telemetry, usernames, and environment variables.
• Fail-close network egress protection: Built-in net ipv6 off, guest iptables airgap (net off), and a fail-close proxy watcher (net-watch) with a companion heartbeat guard ensure VMs are immediately cut off if your host TUN proxy drops, preventing accidental direct-connection IP leaks.
• Persistent login & session registry: Credentials and transcripts live in a per-profile Docker volume (blackhole-claude-home-<profile>), with SessionStart / SessionEnd hooks tracking profile <-> session <-> host path.
• Clipboard image passthrough & visual identity: Pasted terminal screenshots in host $TMPDIR are mirrored read-only at identical paths inside the container, while a persistent magenta ⬤ BLACKHOLE status line badge makes isolated sessions unmistakable.

Usage

Tip: Let an agent drive it. You do not need to memorize every subcommand below. Point your host coding agent at this repository (see AGENTS.md) and let it handle setup, Colima profile binding, .blackhole/Dockerfile tool customization, net-watch protection, and session exports or migrations on your behalf.

Run claude inside any project directory under $HOME:

$ cd ~/Code/my-app
$ claude
 ⬤ BLACKHOLE  Colima VM isolated session · default
/Users/you/Code/my-app (only this directory is mounted)

All standard arguments pass straight through to Claude Code inside the VM:

claude -p "explain this repository"
claude --resume

Check launcher protection, image state, and active containers from another terminal:

$ blackhole status
Colima profile: default
Claude launcher: protected (/Users/you/.local/bin/claude)
Colima:         running
Image:          blackhole-claude:latest
Image status:   built
Claude Code:    1.0.x (Claude Code)
Image ID:       sha256:...
Config volume:  blackhole-claude-home-default
Active sessions:
  blackhole-default-48210  /Users/you/Code/my-app

Bind a project directory to a dedicated Colima VM profile (inherited by subdirectories, stored in ~/.blackhole/bindings/ outside the repo):

$ cd ~/Code/heavy-repo
$ blackhole bind work
blackhole: bound /Users/you/Code/heavy-repo -> profile 'work'

Inspect profiles, recorded sessions across all running VMs, and resume any session by ID prefix from anywhere:

$ blackhole profiles
PROFILE  STATUS   MEMORY  BLACKHOLE  PROJECTS  SESSIONS  LAST USED
default  Running  8GiB    yes        3         12        2026-11-08 11:20
work     Running  16GiB   yes        1         4         2026-11-08 12:05
scratch  Stopped  4GiB    -          -         -         -

$ blackhole sessions
PROFILE  SESSION                               PATH                        STARTED           LAST ACTIVE       STATUS
work     89e4f9ec-8960-4175-9bb0-4bbea4780fa9  /Users/you/Code/heavy-repo  2026-11-08 10:12  2026-11-08 12:05  ended

$ blackhole resume 89e4
blackhole: resuming 89e4f9ec-8960-4175-9bb0-4bbea4780fa9 on profile 'work' in /Users/you/Code/heavy-repo

Open an interactive debugging shell in the exact same isolated container environment:

blackhole shell

Install

Requires macOS, Colima, and the Docker CLI (brew install colima docker). You do not need to install Claude Code or Node.js on the host (blackhole setup installs @anthropic-ai/claude-code inside the VM image). Start your Colima VM with Apple Virtualization (vz) and virtiofs for near-native filesystem performance:

colima start --vm-type vz --mount-type virtiofs --cpu 4 --memory 8 --disk 60

Build the base image and install the claude and blackhole symlinks (defaults to ~/.local/bin):

git clone https://github.com/tommy0103/blackhole.git ~/Code/blackhole
cd ~/Code/blackhole
./bin/blackhole setup
./bin/blackhole install

Ensure ~/.local/bin precedes other binary directories in your PATH:

export PATH="$HOME/.local/bin:$PATH"

To install into another directory or replace an existing host claude binary:

./bin/blackhole install --prefix /opt/homebrew/bin --force

To uninstall, remove the symlinks (rm -f ~/.local/bin/claude ~/.local/bin/blackhole) and optionally remove ~/.blackhole, the blackhole-claude:latest image, and blackhole-claude-home-* Docker volumes.

CLI & Configuration

Subcommands

Environment Variables

Per-Project Linux Tools

macOS Mach-O binaries under /opt/homebrew/bin cannot run inside a Linux VM. To give a project extra Linux CLI tools or build dependencies, create .blackhole/Dockerfile:

ARG BLACKHOLE_BASE=blackhole-claude:latest
FROM ${BLACKHOLE_BASE}

RUN apt-get up