English | 简体中文

BlackHole

BlackHole is a local MCP bridge that gives web-based AI agents controlled access to your local development workspace.

Remote agents connect through MCP Streamable HTTP and can inspect files, edit code, and run commands using a deliberately small tool surface. Every workspace operation is scoped to a session, while destructive, high-risk, or out-of-bound actions are held for explicit human approval.

Web AI (ChatGPT / other MCP-capable agents)
        ↕ MCP Streamable HTTP
Persistent or quick tunnel
        ↓
BlackHole daemon (localhost only)
        ↓
Your local workspace

Why BlackHole?

BlackHole is designed for a simple use case: let a remote AI agent do real development work on your machine without giving it unrestricted machine access.

• Local execution — your real shell, repository, dependencies, and developer tools stay on your machine.

• Workspace boundaries — file operations are constrained to the selected workspace.

• Human approval gates — risky or destructive shell operations pause until you approve or deny them.

• Persistent sessions — sessions, tool calls, todos, events, and approvals survive reconnects.

• Small MCP surface — agents primarily work through pwsh and workspace_editor, with optional semantic code search.

• VS Code integration — create and manage sessions, inspect calls, and approve operations from the sidebar.

• MCP Apps panel — supported hosts can render live task progress and tool activity directly in the conversation.

Related MCP server: codex-web-bridge

Quick Start

From source

pnpm install
pnpm build
pnpm start

The daemon listens on 127.0.0.1:7306 by default.

Create a session for a project:

node dist/cli.js create D:/path/to/project --copy prompt

Check tunnel status:

node dist/cli.js tunnel

BlackHole does not automatically expose the daemon publicly. Start a public channel only when you need one:

# Persistent named tunnel (recommended)
# Set BLACKHOLE_PUBLIC_URL to your stable public URL first.
node dist/cli.js tunnel start named

# Temporary Cloudflare Quick Tunnel
node dist/cli.js tunnel start quick

# Stop the active tunnel
node dist/cli.js tunnel stop

VS Code Extension

The VS Code extension in packages/vscode is the recommended user-facing entry point. It provides:

• session creation and management;

• connector and sandbox prompt generation;

• live tool-call history;

• task progress;

• human approval UI for risky commands;

• daemon start / attach / stop / restart controls;

• public-channel management.

The extension launches the daemon using VS Code's bundled Electron runtime (ELECTRON_RUN_AS_NODE), so end users do not need to install Node.js separately.

Build or package the extension:

pnpm --filter blackhole-vscode build
pnpm --filter blackhole-vscode package

MCP Tools

pwsh

A persistent PowerShell session. The working directory, environment, and shell state survive across calls. High-risk operations are blocked until explicitly approved.

On Windows, the shell also runs under an ACL-restricted token so writes outside the workspace and the session-private temp directory can be rejected by the OS itself.

workspace_editor

Purpose-built workspace file operations:

view / create / str_replace / insert / delete

Paths are guarded and constrained to the active workspace.

context_search (optional)

Semantic code navigation for questions such as:

Where is uploaded content validated before it is sent?

It returns relevant files, line ranges, and code excerpts. The tool is registered only when a supported semantic-search credential is available.

Unlike the core local tools, context_search may send workspace paths and code excerpts to the configured Devin/Windsurf endpoint. It is therefore opt-in and absent from the MCP tool list when no credential is configured.

guide

Returns the BlackHole operating rules that tell the agent how to use the workspace tools, approval model, task contract, and verification workflow.

show

For hosts with MCP Apps support, show mounts the live BlackHole session panel for the current conversation round.

Human Approval Model

BlackHole separates ordinary development work from operations that deserve human attention.

In the default workspace-write mode:

• normal workspace reads and edits proceed automatically;

• destructive, system-level, security-sensitive, or out-of-scope commands pause for approval;

• approval resumes the blocked call rather than asking the agent to retry it;

• denied operations fail without execution.

A session can also run in read-only mode, which rejects mutations entirely.

Approval decisions can be made through the local VS Code / CLI control plane or, for supported MCP Apps hosts, through the embedded session panel.

Security Model

BlackHole uses multiple boundaries rather than relying on a single prompt-level instruction.

Workspace boundary

workspace_editor guards paths against traversal, symlink, and realpath escapes.

Shell policy boundary

Potentially dangerous commands are classified and held behind an approval gate.

Windows kernel boundary

On Windows, shell processes use a restricted ACL token. Approval does not disable this restriction: even an approved command cannot write outside locations granted to the sandbox token.

macOS and Linux currently rely on the policy layer and workspace/editor guards; they do not yet have an equivalent kernel-level write sandbox.

Session credentials

Sessions use opaque numeric credentials. Rotating a credential invalidates the previous one while preserving the session state; revoking a session terminates access.

External data flow

The core workspace and shell tools execute locally. The optional context_search capability is the exception: it can send repository paths and code excerpts to a configured third-party semantic-search endpoint.

MCP Apps Session Panel

BlackHole includes an experimental MCP Apps UI for compatible hosts.

Calling show mounts a lightweight session panel that can display:

• current task / todo progress;

• tool calls from the active round;

• call status and durations;

• workspace edit deltas;

• pending approval actions.

The UI template uses the stable resource URI:

ui://blackhole/panel.html

Per-session routing data is delivered separately in the show result. A new show call creates a new panel capability and invalidates the previous panel for that session.

Hosts without MCP Apps support simply ignore the UI metadata; the MCP tools continue to work normally.

CLI

Configuration

Common environment variables:

Development & Verification

Build:

pnpm build

Run the end-to-end smoke suite:

pnpm smoke

Verify prompt contracts:

pnpm verify:prompts

The repository also contains focused tunnel, semantic-search, sandbox, and VS Code webview checks under scripts/.

Project Structure

src/                    daemon, MCP tools, storage, sandbox, panel
packages/vscode/        VS Code extension
client/                  lightweight client/bootstrap code
scripts/                 smoke tests and verification utilities
docs/                    implementation and extension design notes
web-agents/              web-agent integration assets

Documentation

• VS Code extension design

• Implementation notes

• 简体中文 README

Status

BlackHole is under active development. The daemon, persistent sessions, approval flow, VS Code extension, tunnel lifecycle, optional semantic search, and MCP Apps session panel are implemented, but interfaces may still evolve before a stable public release.

src/index.js is a first-generation prototype. The current daemon implementation is based on src/daemon.ts and dist/cli.js.