How to Configure the WSLC Backend in MXC: Complete Setup Guide

To configure the WSLC backend in MXC, compile the binary with the wslc Cargo feature, ensure the WSLC SDK (wslcsdk.dll) is adjacent to wxc-exec.exe on Windows 11, and execute with the --experimental flag while setting "containment": "wslc" and the experimental.wslc configuration object.

The WSLC (WSL Container) backend is an experimental containment option in the Microsoft eXecution Context (MXC) project that enables Linux container execution on Windows 11 via the WSL Container SDK. Unlike standard WSL 2, this backend provides isolated container sessions with policy-driven resource constraints through MXC's sandboxing layer. Configuring it requires satisfying three distinct requirements: runtime prerequisites, build-time feature flags, and specific JSON schema declarations.

Prerequisites for WSLC Backend Configuration

Windows 11 and WSL 2 Setup

The WSLC backend requires a Windows 11 host with WSL 2 installed and the VM Platform optional component enabled. This backend does not support Windows 10 or WSL 1. The operating system must have the WSL 2 kernel available to host the container sessions that MXC orchestrates.

WSLC SDK Placement

Download the WSLC SDK and place wslcsdk.dll in the same directory as wxc-exec.exe. MXC uses dynamic runtime loading via FFI bindings, so the DLL must be discoverable at launch. The repository includes scripts/setup-wslc.ps1 to automate SDK installation and optional image pre-caching.

Build-Time Configuration

Enabling the wslc Cargo Feature

You must compile MXC with the wslc feature enabled. The code in src/backends/wslc/common/src/wsl_container_runner.rs and the FFI definitions in src/backends/wslc/common/src/wslc_bindings.rs are conditionally compiled behind this feature flag.

Run the following command to build with WSLC support:

cargo build --release --features wslc

If you attempt to use the WSLC backend without this feature, src/core/wxc/src/main.rs emits the error Error: WSLC backend not compiled. Rebuild with --features wslc. and aborts immediately.

Runtime Configuration

Experimental Flag Requirement

Because the WSLC backend is experimental, you must explicitly opt-in via the --experimental CLI flag. In src/core/wxc/src/main.rs, the dispatcher validates this flag before routing "containment": "wslc" requests to WSLContainerRunner. When using the TypeScript SDK, set experimental: true in the spawn options to automatically append this flag.

JSON Schema Configuration

The configuration file must declare "containment": "wslc" at the root level and define WSLC-specific options under the experimental.wslc object. According to schemas/stable/mxc-config.schema.0.5.0-alpha.json, valid fields include:

• image: The container image reference (e.g., python:3.12)
• cpuCount: Number of vCPUs allocated to the container
• memoryMb: Memory limit in megabytes
• gpu: Boolean flag for GPU passthrough
• storagePath: Host directory for container storage
• imageTarPath: Optional path to a pre-exported image tar file

SDK Initialization and Lifecycle

COM Initialization and DLL Loading

When MXC instantiates WSLContainerRunner, the constructor calls CoInitializeEx to prepare COM for Windows API interaction, then loads wslcsdk.dll via the FFI bindings defined in src/backends/wslc/common/src/wslc_bindings.rs. This initialization sequence establishes the connection to the WSL Container SDK.

Pre-Flight Validation

The WslcCanRun() function performs prerequisite checks before attempting container creation. It verifies that the WSLC runtime DLL is accessible, the VM Platform Windows feature is enabled, and the WSL optional component is installed. If any check fails, the runner aborts with a descriptive error before allocating resources.

Container Execution Flow

The WSLContainerRunner implements the ScriptRunner trait with the following lifecycle:

1. Image Handling: If experimental.wslc.imageTarPath is provided, the runner imports the tar file into a new WSLC session. Otherwise, it expects the image to exist in the WSLC cache from a pre-pull operation.
2. Session Creation: A WSLC session is established with CPU, memory, GPU, and storage constraints derived from the MXC SandboxPolicy.
3. Process Launch: The container process starts via WslcProcessCreate, with stdout/stderr handles wrapped in Rust RAII guards that stream data back to the ScriptResponse.
4. Cleanup: When the guard objects drop, the session, container, and process handles release automatically, and temporary image files delete if applicable.

Practical Configuration Examples

Minimal JSON Configuration

Create a file named wslc-config.json:

{
  "version": "0.5.0-alpha",
  "containment": "wslc",
  "experimental": {
    "wslc": {
      "image": "python:3.12",
      "cpuCount": 2,
      "memoryMb": 1024,
      "gpu": true,
      "storagePath": "C:\\wslc\\storage"
    }
  },
  "process": {
    "commandLine": "python -c \"print('Hello from WSLC')\""
  },
  "filesystem": {
    "readonlyPaths": [],
    "readwritePaths": []
  },
  "network": {
    "allowOutbound": true
  },
  "timeoutMs": 30000
}

Command Line Build and Execution

Execute these commands in PowerShell or CMD:

# Build with WSLC support

cargo build --release --features wslc

# Pre-pull the image (optional)

.\scripts\setup-wslc.ps1 -Image python:3.12

# Run with experimental flag

.\target\release\wxc-exec.exe --experimental wslc-config.json

TypeScript SDK Implementation

import {
  createConfigFromPolicy,
  spawnSandboxFromConfig,
} from '@microsoft/mxc-sdk';

const cfg = createConfigFromPolicy({
  version: '0.5.0-alpha',
  containment: 'wslc',
  experimental: {
    wslc: {
      image: 'python:3.12',
      cpuCount: 2,
      memoryMb: 1024,
      gpu: true,
    },
  },
  process: { commandLine: "python -c \"print('Hello from WSLC')\"" },
});

const child = spawnSandboxFromConfig(cfg, { experimental: true });
child.stdout!.on('data', d => process.stdout.write(d));
child.on('close', code => console.log('exit:', code));

The TypeScript SDK serializes the experimental.wslc block exactly as the JSON schema expects and automatically appends the --experimental flag to the CLI invocation.

Summary

• To configure the WSLC backend in MXC, you need Windows 11 with WSL 2, the wslc Cargo feature enabled at compile time, and the --experimental flag at runtime.
• Place wslcsdk.dll next to the executable to satisfy the dynamic loading requirements in src/backends/wslc/common/src/wslc_bindings.rs.
• Use the experimental.wslc configuration object to specify container images, resource limits, and storage paths according to schemas/stable/mxc-config.schema.0.5.0-alpha.json.
• The WSLContainerRunner in src/backends/wslc/common/src/wsl_container_runner.rs handles COM initialization, pre-flight checks via WslcCanRun(), and process lifecycle management via WslcProcessCreate().

Frequently Asked Questions

What are the system requirements for the WSLC backend?

The WSLC backend requires Windows 11 with the WSL 2 and VM Platform optional components installed. Windows 10 is not supported because the WSL Container SDK relies on Windows 11-specific container primitives.

Why does MXC require the --experimental flag for WSLC?

The --experimental flag is mandatory because the WSLC backend is marked as experimental in the codebase. The dispatcher in src/core/wxc/src/main.rs explicitly checks for this flag before routing requests to WSLContainerRunner, ensuring users acknowledge the non-production status of the feature.

How do I pre-pull container images for WSLC?

Use the scripts/setup-wslc.ps1 helper script to install the WSLC SDK and cache images, or execute wxc-exec.exe with the --setup-wslc flag. Alternatively, specify experimental.wslc.imageTarPath in your JSON configuration to import a local tar file directly during container creation.

What happens if I build without the wslc feature?

If you attempt to use "containment": "wslc" without compiling with --features wslc, the binary outputs Error: WSLC backend not compiled. Rebuild with --features wslc. to stderr and exits immediately, as the WSLContainerRunner implementation is excluded from the build.

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