Blackhole

English · 中文

Run Claude Code in a Linux container using Colima on macOS or an existing Docker engine on Linux/Windows WSL2. Only the current project directory is mounted, and login volumes persist between sessions. Windows clipboard capture and proxy-only network access are available on WSL2.

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 does not need to be installed on the host — the actual @anthropic-ai/claude-code package lives inside the Docker image. Typing claude in a project starts an ephemeral Linux container using Colima on macOS or the existing Docker engine on Linux/WSL2. The Colima features below have Docker equivalents described under installation and network control:

• 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
Backend:        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

macOS

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

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗