How to Enable and Configure the Windows Sandbox Backend in Microsoft MXC

To enable the Windows Sandbox backend in the Microsoft MXC framework, set "containment": "windows_sandbox" in your sandbox configuration JSON, enable the Windows Sandbox Windows feature via DISM, and execute scripts using wxc-exec --experimental.

The Windows Sandbox backend provides VM-level isolation for executing untrusted code in the microsoft/mxc repository. Unlike the default process-container backend, this implementation launches scripts inside a temporary Windows Sandbox virtual machine through the WindowsSandboxScriptRunner component, offering complete kernel-level separation from the host system.

Prerequisites for the Windows Sandbox Backend

The Windows Sandbox backend requires Windows 11 Pro or Enterprise with the Windows Sandbox feature installed. This backend cannot run on Home editions or systems without virtualization support.

You must enable the feature using DISM and restart the computer:

dism /online /enable-feature /featurename:Containers-DisposableClientVM /all
Restart-Computer

Verify the installation with:

dism /online /get-featureinfo /featurename:Containers-DisposableClientVM

The check_sandbox_available function in src/backends/windows_sandbox/common/src/windows_sandbox_runner.rs (lines 92-108) performs this exact runtime verification before attempting to launch the VM.

Architecture and Component Overview

The Windows Sandbox backend consists of three main processes coordinated across the host and guest boundaries.

CLI Entry Point – wxc-exec.exe forwards execution to WindowsSandboxScriptRunner, defined in src/backends/windows_sandbox/common/src/windows_sandbox_runner.rs.

Host Daemon – wxc-windows-sandbox-daemon.exe (crate wxc_windows_sandbox_daemon) manages the VM lifecycle. It generates .wsb configuration files, launches WindowsSandbox.exe, creates a rendezvous file, and opens four TCP channels (control, stdin, stdout, stderr) for IPC.

Guest Agent – wxc-windows-sandbox-guest.exe runs inside the sandbox VM. It binds TCP ports, writes the connection details to the rendezvous file, locks down the firewall to allow only the host IP, and executes scripts via cmd.exe /C.

When the daemon is not running, WindowsSandboxScriptRunner::ensure_daemon_running (lines 58-89 in the runner source) automatically launches it as a detached process and polls until the IPC port becomes reachable.

Configuration Schema and JSON Options

A valid sandbox JSON must specify the backend type and process details. The WindowsSandboxConfig model in src/core/wxc_common/src/models.rs (lines 180-191) defines the available fields.

{
  "version": "0.5.0-alpha",
  "containment": "windows_sandbox",
  "process": {
    "commandLine": "python -S -B -c \"print('hello')\"",
    "timeout": 60000
  },
  "experimental": {
    "windows_sandbox": {
      "idleTimeoutMs": 300000,
      "daemonPipeName": "wxc-windows-sandbox"
    }
  }
}

• containment – Must be exactly "windows_sandbox" to select this backend.

• process.commandLine – The command executed inside the sandbox VM.

• experimental.windows_sandbox.idleTimeoutMs – Default 300000 (5 minutes). Controls how long the daemon keeps the VM alive after the last execution.

• experimental.windows_sandbox.daemonPipeName – Determines the deterministic TCP port for IPC via WindowsSandboxScriptRunner::pipe_name_to_port (lines 30-37 in the runner source).

Standard filesystem and network sections are ignored; isolation is enforced solely by the VM boundary and guest-agent firewall rules.

Enabling Windows Sandbox on the Host

Before running configurations, ensure the Windows feature is active. The backend relies on the Containers-DisposableClientVM feature, which provides the base Windows Sandbox functionality.

Enable it using the same DISM commands shown in the Prerequisites section. The daemon will fail to start with a descriptive error if this feature is missing, as verified by the runtime check in check_sandbox_available.

Running Scripts with the Experimental Backend

Because Windows Sandbox support is experimental, you must invoke the CLI with the --experimental flag:

wxc-exec --experimental my_sandbox.json

On first execution, the runner automatically spawns wxc-windows-sandbox-daemon.exe if it is not already running. The daemon persists according to the idleTimeoutMs setting, allowing subsequent script executions to reuse the warm VM and avoid 15-60 second cold-boot latency.

Security Isolation Model

The Windows Sandbox backend implements defense in depth through full virtualization. Scripts execute in a pristine Windows instance with an isolated registry, filesystem, and network stack.

Firewall Lockdown – The guest agent creates a Windows firewall rule allowing only the host IP to connect to the TCP ports.

Ephemeral Execution – The VM is destroyed when the daemon's idle timeout expires or when the daemon exits, ensuring no persistent state between runs.

Read-Only Mounts – The host binaries and Python interpreter are mounted read-only inside the VM, preventing guest modifications to the execution environment.

Known Limitations and Constraints

Limitation	Details
Cold-boot latency	First VM launch takes 15–60 seconds; subsequent executions reuse the running instance.
Language mapping	Only Python binaries are automatically mapped into the VM; other runtimes require manual configuration.
TCP-port collisions	IPC uses a deterministic TCP port derived from daemonPipeName; conflicts occur if another process binds the same port.
Buffered I/O	stdout and stderr are buffered and returned after script completion; live streaming is not supported.
Policy restrictions	filesystem and network configuration sections are ignored; isolation relies entirely on the VM boundary.

Summary

• The Windows Sandbox backend provides VM-level isolation by setting "containment": "windows_sandbox" and requires Windows 11 Pro/Enterprise with the Containers-DisposableClientVM feature enabled.
• Architecture involves wxc-exec.exe → WindowsSandboxScriptRunner → wxc-windows-sandbox-daemon.exe → wxc-windows-sandbox-guest.exe with four TCP channels for IPC.
• Configuration controls VM lifetime via idleTimeoutMs and IPC port derivation via daemonPipeName in the experimental section.
• Execution requires the --experimental flag; the daemon manages VM pooling automatically to mitigate cold-start latency.
• Security relies on full VM isolation, ephemeral instances, and firewall rules enforced by the guest agent.

Frequently Asked Questions

What are the system requirements for the Windows Sandbox backend?

The backend requires Windows 11 Pro or Enterprise with the Windows Sandbox feature enabled via DISM. It does not support Windows Home editions, and the check_sandbox_available function in windows_sandbox_runner.rs verifies these requirements at runtime.

Why is the --experimental flag required to use the Windows Sandbox backend?

The Windows Sandbox backend is currently marked as experimental in the microsoft/mxc codebase, meaning its API and behavior may change. You must append --experimental to wxc-exec commands to acknowledge this status and enable the functionality.

How does the daemonPipeName configuration affect TCP port allocation?

The daemonPipeName string is hashed by WindowsSandboxScriptRunner::pipe_name_to_port to generate a deterministic TCP port number for host-daemon communication. Changing this name avoids port collisions if the default port is already in use by another application.

Can I customize network or filesystem policies when using the Windows Sandbox backend?

No. The filesystem and network sections in your sandbox JSON are ignored when using this backend. Isolation is enforced strictly by the Windows Sandbox VM boundary and the internal firewall rules configured by the guest agent, not by MXC's policy engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}