BlackHole

Connect Web Agents to your local workspace, shell and MCP tools with explicit execution boundaries.

BlackHole is an open-source VS Code extension by qianshe. It gives Web Agents controlled access to the current local workspace while keeping sessions, permissions, approvals and activity visible in VS Code.

Status: Early release. The extension currently focuses on local VS Code workspaces.

What you can do

• Create a workspace session — bind an AI session to the current project.
• Connect over MCP — start a temporary or persistent tunnel and copy the MCP connection information when needed.
• Use web AI agents — choose a configured web agent and copy a ready-to-use prompt for either a connector workflow or direct MCP access.
• Review tool activity — see tool calls, commands, statuses, and result summaries from the session panel.
• Control sessions — pause, resume, revoke, or rotate a session key without changing the MCP URL.
• Approve sensitive operations — high-risk commands can require explicit approval in VS Code.
• Keep the daemon independent — the daemon can continue running when VS Code windows are closed; it can be stopped or restarted from the extension.

Quick start

1. Install BlackHole — Web Agent Bridge from the VS Code Marketplace by publisher qianshe. Before the Marketplace listing is live, install the provided .vsix with Extensions → … → Install from VSIX….
2. Install cloudflared for your operating system when you need a public channel. Follow the channel setup guide, or set blackhole.cloudflaredPath to an existing executable. The VSIX does not bundle or download it.
3. Open a local workspace, sign in, and create a BlackHole session.
4. Start a temporary (quick) or persistent (named) channel from the session/settings UI. Named channels use a locally managed Cloudflare tunnel and a fixed public URL. Quick tunnels are for testing and do not support SSE.
5. Copy the generated MCP connection information or the ready-to-use AI prompt.
6. Open your web AI agent and follow the copied prompt to connect it to the workspace.
7. Monitor tool calls and approve sensitive operations from VS Code when prompted.

MCP connection modes

BlackHole supports two practical workflows:

• Connector workflow: use a preconfigured BlackHole connector and copy a prompt containing the current session key.
• Direct MCP workflow: give the web AI agent the MCP URL and session key so its sandbox can connect directly when public network access is available.

The MCP URL represents the machine-level connection endpoint; session keys control access to individual sessions. Rotating a session key invalidates the previous key while keeping the MCP URL unchanged.

Security model

BlackHole is designed around explicit user control:

• Sessions are bound to the selected local workspace.
• The default permission mode is workspace-write; read-only and danger-full-access are also available according to the session permission model.
• High-risk operations can require approval before execution.
• Session credentials are not persisted in plaintext by the VS Code extension; the extension keeps the active session key in memory.
• The daemon stores credential material as hashes and only exposes a newly created session key once.

Review permissions before giving an AI agent access to a workspace. Restricted command execution uses a Windows write-restricted token, Linux bubblewrap, or macOS Seatbelt. read-only does not grant workspace writes; workspace-write grants the selected workspace, explicitly authorized directories and a private temporary directory. If a required runner is missing or fails to initialize, commands are refused instead of running unconfined.

These controls limit file writes, not all file reads, network access or interactions with other host services. Windows ACL restrictions also have limitations around objects writable by Everyone and hard links. They are not a security boundary for running arbitrary hostile software. Use a disposable VM/container for untrusted code and keep backups.

danger-full-access deliberately removes command write confinement. Configured MCP upstream programs run with their own host/service permissions; the session shell sandbox does not automatically contain those programs. Only configure upstreams you trust.

Privacy and cloud boundary

• Signing in sends only the authentication flow data needed by BlackHole Cloud. Session bearer tokens are stored in VS Code SecretStorage; the extension keeps only non-secret login/logout receipts in its global storage.
• Signing in, checking subscription status, or purchasing time does not upload your workspace files to BlackHole Cloud.
• Workspace files, commands and tool calls are handled by the local BlackHole daemon. Content can leave your machine when you explicitly connect a Web Agent or MCP upstream and ask it to use those capabilities; that third party's own privacy terms then apply.
• contextsearch uses Devin Fast Context. It is available only after a Devin Key is configured; the code context required for a search is sent to Devin and is also subject to Devin's terms and privacy policy.
• The extension currently implements no independent product telemetry or advertising tracker.
• Account, subscription and payment operations use BlackHole Cloud. Payment checkout and provider confirmation are handled through Alipay; do not put payment credentials, private keys or subscription-card codes in a workspace or chat.

Privacy policy: https://blackhole.stellarbridge.dpdns.org/privacy

Terms: https://blackhole.stellarbridge.dpdns.org/terms

Configuration

Open Settings → BlackHole to configure options such as:

• Local daemon port (default: 7306)
• Daemon entry point override for development
• cloudflared path override
• Persistent public base URL / named tunnel
• Tunnel probe proxy
• Web AI agent list and custom web-agent sites
• Polling interval
• Skills library directory
• Semantic search credential policy

Most users can keep the defaults and start with a local workspace.

Requirements and current limitations

• VS Code 1.107.0 or newer, to provide the Node 22 runtime used by the bundled daemon. Current desktop VS Code is recommended.
• One universal VSIX, version 0.3.130, without a bundled tunnel binary. Windows x64 includes its native sandbox runtime; Linux and macOS do not load that runtime.
• Linux restricted commands require /usr/bin/bwrap (bubblewrap) and working user namespaces. macOS restricted commands require the system /usr/bin/sandbox-exec. Missing backends fail closed; installing a universal VSIX does not prove every OS configuration is supported.
• Windows ARM/32-bit native execution and VS Code for the Web are not supported by this candidate. Linux/macOS native smoke tests must pass before advertising full platform support.
• cloudflared is needed only for Cloudflare channels. Install it for the actual OS/CPU and validate cloudflared --version; after changing PATH, restart both VS Code and the already-running BlackHole daemon.
• Multi-root workspace support requires choosing a folder for the session. Remote SSH/WSL/container extension-host workflows are not part of this release.

Versioning

The current candidate remains 0.3.130. Local debugging and rebuilds do not change the version. Increment the patch only when distributing a distinguishable update. Cloud services are deployed independently; neither building nor packaging publishes anything.

Troubleshooting

The MCP URL cannot be reached

Check the channel status in BlackHole and verify that the selected public URL/tunnel is running. For a persistent channel, make sure blackhole.publicBaseUrl is configured correctly.

The web AI cannot connect directly

Some web AI sandboxes do not provide public network access. Use the connector workflow when available, or use an environment that can reach the MCP URL.

The session key no longer works

Rotate the session key from the session panel and copy the generated prompt again. The previous key is invalidated after rotation.

Documentation

Design and implementation notes under docs/ are local maintainer material and are not distributed with this repository or VSIX. Use this README for the extension usage guide.

Feedback

If you find a bug or have a feature request, please include the VS Code version, BlackHole extension version, operating system, and relevant daemon/session logs when possible.