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

> Learn how to configure the WSLC backend in MXC. Follow our guide to compile with the wslc feature, set up the SDK, and execute with the experimental flag for seamless integration. Get started today.

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

---

**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`](https://github.com/microsoft/mxc/blob/main/src/backends/wslc/common/src/wsl_container_runner.rs) and the FFI definitions in [`src/backends/wslc/common/src/wslc_bindings.rs`](https://github.com/microsoft/mxc/blob/main/src/backends/wslc/common/src/wslc_bindings.rs) are conditionally compiled behind this feature flag.

Run the following command to build with WSLC support:

```bash
cargo build --release --features wslc

```

If you attempt to use the WSLC backend without this feature, [`src/core/wxc/src/main.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/wslc-config.json):

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

```bash

# 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

```typescript
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`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/schemas/stable/mxc-config.schema.0.5.0-alpha.json).
- The `WSLContainerRunner` in [`src/backends/wslc/common/src/wsl_container_runner.rs`](https://github.com/microsoft/mxc/blob/main/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`](https://github.com/microsoft/mxc/blob/main/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.