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

> Learn to enable and configure the Windows Sandbox backend in Microsoft MXC. Follow simple steps to set containment, enable the feature, and execute scripts for enhanced security and testing.

- Repository: [Microsoft/mxc](https://github.com/microsoft/mxc)
- Tags: tutorial
- Published: 2026-06-07

---

**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:

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

```

Verify the installation with:

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

```

The `check_sandbox_available` function in [`src/backends/windows_sandbox/common/src/windows_sandbox_runner.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/src/core/wxc_common/src/models.rs) (lines 180-191) defines the available fields.

```json
{
  "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:

```powershell
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`](https://github.com/microsoft/mxc/blob/main/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.