Microsoft eXecution Container (MXC)

MXC is a sandboxed code execution system for running untrusted code (model output, plugins, tools) on Windows, Linux, and macOS. It provides multiple containment backends — from OS-native process sandboxes to full VMs — behind a unified JSON configuration schema and TypeScript SDK.

Features

• Cross-platform: Windows, Linux, and macOS support with platform-appropriate containment backends
• JSON-based Configuration: Define execution parameters and security policies via a versioned JSON schema
• Multiple Containment Backends: ProcessContainer, Windows Sandbox, LXC, Bubblewrap, Seatbelt (macOS), MicroVM (NanVix), Hyperlight, IsolationSession, and WSLC
• Policy-driven Sandboxing:
  • Filesystem Policy: Read-only and read-write path lists (denied paths not yet supported on Windows)
  • Network Policy: Proxy support (not supported on macOS); allow/block outbound and host filtering (not yet supported on Windows)
  • UI Policy: Clipboard, display, and GUI access controls
• State-aware Lifecycle: Multi-step sandbox lifecycle (provision → start → exec → stop → deprovision) for session sandboxes
• TypeScript SDK: @microsoft/mxc-sdk npm package with one-shot and state-aware APIs
• Diagnostics: Debug logging and Event Tracing for Windows (ETW) for troubleshooting

Building

MXC ships a native container wrapper plus a TypeScript SDK — see the SDK README for full API documentation.

Platforms

Platform	Default backend	Other backends	Minimum build
Windows 11 24H2+ (verified on 25H2)	processcontainer	windows_sandbox, wslc, microvm, hyperlight, isolation_session	processcontainer: 26100 (24H2) isolation_session: 26300.8553 (Insider Preview)
Linux x64 / ARM64	bubblewrap	lxc, microvm, hyperlight	—
macOS ARM64 / x64 (schema 0.7.0-alpha+)	seatbelt	—	—

The stable one-shot backends (processcontainer, bubblewrap, lxc, and seatbelt) do not require experimental mode; Linux hosts also need the matching runtime installed: bwrap (Bubblewrap) for the default backend, or the lxc toolset for the lxc backend. Experimental backends (windows_sandbox, wslc, microvm, isolation_session, hyperlight) require { experimental: true } in SandboxSpawnOptions or the --experimental CLI flag.

Requirements

• Rust toolchain — version pinned to 1.93 via src/rust-toolchain.toml (auto-selected by rustup)
• Node.js ≥ 18
• npm (for SDK and CLI builds)

Project Structure

src/        Rust workspace (native binaries + shared library crates)
sdk/        TypeScript SDK (@microsoft/mxc-sdk npm package)
schemas/    JSON configuration schemas (stable + dev)
docs/       Documentation (schema reference, backend guides, design docs)
tests/      Test collateral (configs, examples, scripts)
scripts/    Build and utility scripts

Full Build

Windows

build.bat                  # Release build for current architecture
build.bat --debug          # Debug build
build.bat --all            # Release build for both x64 and ARM64
build.bat --with-microvm   # Include NanVix micro-VM binaries

Linux

./build.sh                 # Release build
./build.sh --debug         # Debug build
./build.sh --rust-only     # Only Rust binaries, skip SDK/CLI

macOS

./build-mac.sh             # Release build for native architecture
./build-mac.sh --all       # Both Apple Silicon and Intel
./build-mac.sh --debug     # Debug build
./build-mac.sh --rust-only # Only Rust binary, skip SDK

All build scripts:

1. Build the platform-appropriate Rust binary

2. Copy the binary into sdk/bin/<arch>/ (for example, x64 or arm64) for SDK bundling

3. Build the TypeScript SDK

Building Components Individually

# Rust workspace (from src/)
cargo build --release --target x86_64-pc-windows-msvc     # Windows x64
cargo build --release --target aarch64-pc-windows-msvc    # Windows ARM64
cargo build --release -p lxc                               # Linux — lxc-exec (serves both LXC and Bubblewrap)
cargo build --release -p mxc_darwin --target aarch64-apple-darwin  # macOS

# SDK (from sdk/)
npm install && npm run build

Lint and Format

# Windows Rust (from src/)

cargo clippy --workspace --all-targets -- -D warnings

# Linux Rust (from src/; matches build.sh's platform-compatible crate set)

cargo clippy -p lxc -p lxc_common -p wxc_common -p bwrap_common -p linux_test_proxy --all-targets -- -D warnings

# macOS Rust (from src/)

cargo clippy -p mxc_darwin -p seatbelt_common --all-targets -- -D warnings

Tests

# Rust unit tests (from src/)
cargo test --workspace
cargo test -p wxc_common                      # Single crate
cargo test -p wxc_common -- config_parser     # Filter by test name

# SDK (from sdk/)
npm test                     # Unit tests
npm run test:integration     # Integration tests

# E2E (from src/)
cargo test -p wxc_e2e_tests

Usage

MXC uses a JSON configuration to define execution parameters. See the schema documentation for full reference.

Native Binary

# File path
wxc-exec.exe config.json

# Base64-encoded config
wxc-exec.exe --config-base64 <base64-encoded-json>

# Debug output
wxc-exec.exe --debug config.json

On Linux: ./lxc-exec config.json On macOS: ./mxc-exec-mac --experimental config.json

TypeScript SDK

npm install @microsoft/mxc-sdk

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

if (!getPlatformSupport().isSupported) {
  throw new Error('MXC not available on this host');
}

const tools = getAvailableToolsPolicy(process.env);
const temp  = getTemporaryFilesPolicy();

const config = createConfigFromPolicy({
  version: '0.6.0-alpha',
  filesystem: {
    readonlyPaths:  tools.readonlyPaths,
    readwritePaths: temp.readwritePaths,
  },
  network: { allowOutbound: false },
  timeoutMs: 30_000,
});
config.process!.commandLine = 'python -c "print(\'hello from sandbox\')"';

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

The SDK also provides a state-aware lifecycle API for long-lived sandboxes:

import {
  provisionSandbox, startSandbox, execInSandboxAsync,
  stopSandbox, deprovisionSandbox,
} from '@microsoft/mxc-sdk';

See the SDK README for full API documentation.

Schema Versions

Released, immutable stable schemas live in schemas/stable/; the in-progress dev schema (experimental backends, state-aware lifecycle) lives in schemas/dev/. The current stable and dev versions are tracked canonically in schemas/schema-version.json.

Pick the latest stable schema for new code on any supported platform. See docs/versioning.md for the full versioning design.

Debugging

Debug Console Mode

By default, native binaries run in silent mode — stdin/stdout/stderr is coupled directly to the container. Use --debug for verbose output:

wxc-exec.exe --debug config.json

See docs/diagnostics.md for full diagnostics reference.

Documentation

Document	Description
docs/schema.md	Full JSON configuration schema reference
docs/versioning.md	Schema versioning and experimental feature lifecycle
docs/examples.md	Annotated configuration examples
docs/host-prep.md	Windows host preparation (wxc-host-prep.exe)
docs/diagnostics.md	Diagnostic logging and ETW
docs/sandbox-policy/v1/policy.md	Sandbox policy v1 specification
docs/base-process-container/guide.md	Windows AppContainer / BaseContainer guide
docs/lxc-support/lxc-backend.md	LXC backend (Linux)
docs/bwrap-support/bubblewrap-backend.md	Bubblewrap backend (Linux)
docs/macos-support/seatbelt-backend.md	Seatbelt backend (macOS)
docs/windows-sandbox/windows-sandbox.md	Windows Sandbox backend
docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md	State-aware sandbox lifecycle API

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

See LICENSE.md for details.