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.
Warning
This repository contains an early preview of code published to enable early integration and feedback from developers on Microsoft Execution Containers. The underlying sandboxes in this early preview are expected to change as they are under ongoing development however we will aim to minimize compatibility impact as functionality evolves. There are known cases where the current policies generated by the MXC SDK in this repository are overly permissive and will be addressed before this is made more generally available. Security researcher partnership while MXC matures is welcome, however no MXC profiles should be treated as security boundaries currently.
- 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-sdknpm package with one-shot and state-aware APIs - Diagnostics: Debug logging and Event Tracing for Windows (ETW) for troubleshooting
MXC ships a native container wrapper plus a TypeScript SDK — see the SDK README for full API documentation.
| 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.6.0-alpha+) |
seatbelt |
— | — |
The stable one-shot backends (processcontainer, bubblewrap, and lxc) 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, seatbelt, isolation_session, hyperlight) require { experimental: true } in SandboxSpawnOptions or the --experimental CLI flag.
- Rust toolchain — version pinned to 1.93 via
src/rust-toolchain.toml(auto-selected byrustup) - Node.js ≥ 18
- npm (for SDK and CLI builds)
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
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./build.sh # Release build
./build.sh --debug # Debug build
./build.sh --rust-only # Only Rust binaries, skip SDK/CLI./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 SDKAll build scripts:
-
Build the platform-appropriate Rust binary
-
Copy the binary into
sdk/bin/<arch>/(for example,x64orarm64) for SDK bundling -
Build the TypeScript SDK
# 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# 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# 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_testsMXC uses a JSON configuration to define execution parameters. See the schema documentation for full reference.
# 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.jsonOn Linux: ./lxc-exec config.json
On macOS: ./mxc-exec-mac --experimental config.json
npm install @microsoft/mxc-sdkimport {
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.
| Version | Status | Schema File |
|---|---|---|
0.5.0-alpha |
Stable | schemas/stable/mxc-config.schema.0.5.0-alpha.json |
0.6.0-alpha |
Stable (current) | schemas/stable/mxc-config.schema.0.6.0-alpha.json |
0.7.0-dev |
Dev (experimental backends, state-aware lifecycle) | schemas/dev/mxc-config.schema.0.7.0-dev.json |
Pick 0.6.0-alpha for new code on any supported platform. See docs/versioning.md for the full versioning design.
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.jsonSee docs/diagnostics.md for full diagnostics reference.
| 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 |
See CONTRIBUTING.md for contribution guidelines.
See LICENSE.md for details.