Kali MCP Sandbox

An isolated Kali Linux tool environment for any MCP-compatible AI client. Runs in a microsandbox microVM, with a small curated tool image, asynchronous jobs and persistent workspaces. CobaltElectron is one integration; the server does not depend on it.

Status

Initial release: Windows x64 / WHP. Linux x64 / KVM and macOS Apple Silicon / HVF are build targets, but are not advertised as release-supported until their real-hypervisor smoke tests pass. Intel macOS is not supported. Python 3.11+ is required by the standalone launcher. Docker is needed to build images, not to run the released microVM.

Windows requires hardware virtualization and the Windows Hypervisor Platform feature (a system restart may be necessary). Run doctor after installation. The launcher never silently enables OS features.

Related MCP server: Kali MCP Server

Quick start

Install the host launcher from a reviewed release tag:

python -m pip install "git+https://github.com/B1a0k/kali-mcp-sandbox.git@v0.2.0"
kali-mcp-sandbox install
kali-mcp-sandbox doctor

install downloads a signed manifest, verifies its pinned Ed25519 key, downloads the matching runtime and Kali archive, verifies sizes and SHA-256, and imports the image. No GitHub account, token, Docker daemon or manually created VM is required by end users. HTTPS proxy environment variables are supported. Domestic artifact mirrors can be added to future signed manifests; no third-party download proxy is assumed.

Configure a stdio MCP server in your client:

{
  "mcpServers": {
    "kali": {
      "command": "kali-mcp-sandbox",
      "args": ["serve", "--workspace", "28ca7588-1267-4fb9-8476-2e1af3239d83"]
    }
  }
}

Use the absolute executable path if your desktop client cannot resolve PATH. Each independent workspace should use its own UUID. Reuse an ID to resume its files and job history. A second live client using the same ID is rejected. Installation is an explicit step: serve never downloads executable code during an MCP handshake.

Choose a physical data directory with --home before the subcommand, consistently for install and serve:

kali-mcp-sandbox --home /path/to/kali-data install
kali-mcp-sandbox --home /path/to/kali-data serve --workspace YOUR-UUID

Windows paths such as E:\KaliData are supported. Defaults live in the user's application-data directory, outside source checkouts. No host folders are mounted into the VM.

Tools and execution contract

Core includes OpenVPN, smbclient, Impacket (including impacket-smbexec and the smbexec compatibility command), ProxyChains 4, NetExec (nxc), smbmap, enum4linux-ng, LDAP/Kerberos clients, socat, SSH tooling, nmap, gobuster, dirb, nikto, sqlmap, whatweb, curl, wget, jq, dig and netcat. Only installed upstream MCP tools are advertised. Additional installed programs can be invoked through execute_command.

Commands run as root inside the isolated microVM. Agents should invoke tools directly and must not waste a turn trying sudo; this does not grant access to the host. OpenVPN can configure routes and TUN devices when the host runtime exposes /dev/net/tun. The sandbox still has its own kernel, filesystem and network boundary.

• execute_command(command, request_id, timeout) returns a jobId, not a completed result. Keep request_id stable for retries of one operation.

• job_read(job_id, cursor, stream, wait_seconds) returns state, output and nextCursor; wait defaults to 5 seconds. Read until a terminal state and inspect the exit code.

• job_cancel(job_id) cancels the process group, not just its parent shell.

• environment_health() reports readiness and active/recent jobs. Inspect it after reconnecting instead of replaying commands.

Default limits: 1 GiB memory, 2 vCPUs, an 8 GiB sparse writable disk, two concurrent guest jobs, 4 MiB per output stream, 16 KiB per read and a one-hour maximum command timeout. Job history has no fixed count limit. New work is rejected below 128 MiB of available workspace disk; existing jobs, results and idempotency receipts are preserved, and the environment is never automatically reset.

Starting in v0.1.2, the signed manifest also includes a small guestService asset. Embedded hosts can verify it, explicitly stop/start an existing VM, then apply the service upgrade without replacing the disk. Image updates are immutable: existing disks remain pinned to the image that created them, while a host integration can retain the previous disk for rollback and create a new instance from the updated image.

Use kali-mcp-sandbox check-update for a machine-readable version check and kali-mcp-sandbox update to install the newest signed runtime and image. uninstall removes runtime/cache files but preserves sandbox disks; uninstall --purge-data --confirm is the explicit destructive variant. Stop live workspaces before either operation.

Network defaults to public; --network none disables networking and --network public,private permits private destinations. TCP/HTTP/DNS are supported; raw packets, ARP, wireless operations and Windows ICMP semantics are not promised. Nmap defaults to TCP connect scanning.

Lifecycle

The VM starts when the MCP client connects and stops when stdio closes normally. Its writable disk persists. SIGINT/SIGTERM also clean up; a forcibly killed launcher may leave a VM running. Reconnecting with the same workspace recovers the stale VM, or use kali-mcp-sandbox stop --workspace ID. Do not mistake this recovery behavior for an immediate parent-death watchdog.

Changing image version, CPU, memory or network for an existing standalone workspace requires a new workspace ID; the old disk is preserved. status lists sandboxes. There is no remote multi-user pool in this release and no isolation between two processes inside the same workspace. The standalone launcher limits each VM, not the total number of distinct workspaces that users launch.

Embedded shared environments

A desktop host can own one persistent VM and multiplex conversations over its MCP connection. Conversation creation and tab closure must not close that host-owned connection. The host must namespace command request IDs, persist each returned job's conversation owner, and restrict automatic cancellation to that owner's jobs. Use separate default working directories to avoid accidental file-name collisions; explicit shared paths and installed tools remain shared. This is coordination within one trusted desktop user, not a security boundary between untrusted tenants. The standalone serve command above retains its single-workspace lease contract.

python scripts/shared_smoke.py --image IMAGE verifies three MCP bridges against an offline disposable container, including reconnect, job persistence, independent cancellation and idempotent receipts.

Build and verify

docker build --build-arg KALI_BASE=kalilinux/kali-rolling@sha256:c717f201f29a7e0a9126c0d51bd08aa7194ac82f53c57314339182f92b0b1585 -t kali-mcp-sandbox:0.2.0-amd64 image
python scripts/docker_smoke.py --image kali-mcp-sandbox:0.2.0-amd64
docker save kali-mcp-sandbox:0.2.0-amd64 -o kali-core-amd64.tar
python scripts/smoke.py --msb PATH_TO_MSB --firmware PATH_TO_LIBKRUNFW --image kali-core-amd64.tar --image-ref kali-mcp-sandbox:0.2.0-amd64

The base is official Kali Linux, with a curated package layer and an adapted MCP service. The base digest and upstream MCP commit are pinned. Kali rolling package indexes still change: rebuildable source does not imply bit-for-bit reproducibility. Releases include exact archive digests and package versions.

See release operations and third-party notices. The project code is MIT-licensed; bundled software retains its own licenses. Kali MCP Sandbox is an independent project, not an official Kali Linux or microsandbox product.