mxc README

The project's README from github.com/microsoft/mxc. As one markdown file: README.md.

Microsoft eXecution Container (MXC)

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

Features

What is MXC?

MXC is an SDK dependency that builds into your app.

flowchart LR
    App["Your application<br/>Launch API"] --> SDK["MXC SDK<br/>Rust / .NET / Node<br/>(in process)"]
    SDK --> Backend["Selected backend<br/>(in process)"]
    Backend --> Container["Isolated workload<br/>ProcessContainer / WSLC / Bubblewrap / ..."]

Your application specifies:

MXC validates the request, selects the backend, and launches the workload in the resulting container.

What container types are supported?

MXC runs workloads through platform-appropriate container backends on Windows, Linux, and macOS.

Runtime platform Default backend Other backends Minimum host OS
Windows 11 x64 / ARM64 processcontainer windows_sandbox*, wslc, microvm*, hyperlight*, isolation_session Windows OS-version support
Linux x64 / ARM64 bubblewrap lxc, microvm, hyperlight -
macOS ARM64 / x64 seatbelt - -

* These backends are experimental.

How do I use MXC?

Install an SDK through your package manager. You do not need to clone this repository.

SDK Package
Rust https://crates.io/crates/mxc-sdk
.NET https://www.nuget.org/packages/Microsoft.Mxc.Sdk
Node https://www.npmjs.com/package/@microsoft/mxc-sdk

The Node and .NET packages include the native runtime assets. The Rust crate builds the MXC SDK, engine, and selected backends into the consuming application.

Non-SDK consumption: Platform-specific executor binaries, such as wxc-exec.exe, accept JSON container-creation requests defined by the stable schema. Use for testing or when the SDK cannot be embedded in your app.

Running a contained workload

For complete SDK samples, see the Rust, .NET, and Node samples.

Sample Node snippet

import { spawn, type ContainerRequest } from '@microsoft/mxc-sdk/v1';

const request: ContainerRequest = {
  command: 'node -e "console.log(\'hello from container\')"',
  network: { egress: { default: 'deny' } },
  timeoutMs: 30_000,
};

const child = await spawn(request);

See the runnable streaming standard-I/O sample and the SDK API reference.

My application won't run in the sandbox!

Your application will hit access issues when running in a sandbox, until you've had time to tune your containment rules. We're here to help.

Debug console mode

Native executors normally reserve standard input, output, and error for the workload. Use --debug for MXC diagnostic output:

wxc-exec.exe --debug config.json

See MXC diagnostics for the complete developer reference.

Audit mode

Warning: --audit turns off all sandbox security for the workload being analyzed. Never use it to run untrusted code.

Audit mode helps a policy author find access-denied failures and reconstruct a ProcessContainer policy that grants the files and capabilities a trusted tool actually needs. On supported Windows releases, run:

wxc-exec.exe --audit policy.json

MXC records the observed accesses and produces policy-authoring artifacts. See logging access denied for safe deny-and-record diagnostics, audit outputs, and supported workflows.

Telemetry

Official Microsoft builds can send optional diagnostic telemetry to Microsoft. Telemetry is off unless the individual run opts in, the Windows user has explicitly consented, administrative policy permits collection, and your application enables the telemetry option in a contained workload request. An administrator can block telemetry but cannot grant consent for the user.

Local open-source builds are not configured to route telemetry to Microsoft, and telemetry is a no-op on non-Windows platforms. See telemetry policy and consent for controls and privacy details.

Building from source

Build from source when developing MXC, changing the native runtime, or using the standalone executor binaries instead of a packaged SDK. Repository builds produce the platform-native runtime and executors and stage the native assets used by the Node SDK.

Build prerequisites are:

Build

Windows

build.bat --all             # Release build for current architecture

Linux

./build.sh --all            # Release build

macOS

./build-mac.sh --all        # Release build for native architecture

Documentation

Consumer documentation

Document Repository location Purpose
Terminology docs/glossary.md Plain-English definitions of consumer terms
SDK samples samples/ Runnable Rust, .NET, and Node scenarios
SDK API reference docs/api-reference/ Supported V1 operations and types
Container lifecycle docs/container-lifecycle.md Persistent container lifecycle overview
Logging access denied docs/logging-access-denied.md Diagnose blocked accesses and author policy
Telemetry docs/telemetry.md Consent and administrative controls
Backend guides docs/backends/ Platform and backend prerequisites and behavior

Repository contributors should start with the MXC development documentation.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

See LICENSE.md for details.

mxc (microsoft/mxc)

Searching Database…

2.9K ·GitHub
Mxc
Что это такое?MXC (Microsoft eXecution Container) — это система изолированного выполнения кода для запуска недоверенного кода — вывода моделей, плагинов и инструментов — на Windows, Linux и macOS, использующая бэкенды изоляции: от нативных для ОС процессных песочниц до полноценных виртуальных машин.
Это самостоятельное приложение или SDK, который я встраиваю в свой код?Это SDK-зависимость, встраиваемая в ваше приложение. Вы указываете тип контейнера, правила изоляции и команду рабочей нагрузки, а MXC проверяет запрос, выбирает бэкенд и запускает нагрузку.
Как добавить MXC в проект?Установите SDK через пакетный менеджер — Rust-крейт, пакет .NET или пакет Node — без клонирования репозитория. Есть также платформенно-специфичные исполняемые файлы исполнителя, вроде wxc-exec.exe, для использования без SDK на основе JSON.
Что будет, если действия моего приложения блокирует песочница?Вы будете получать ошибки отказа в доступе, пока не настроите правила изоляции; MXC предлагает режим отладочной консоли для диагностики и режим аудита, отключающий всю защиту песочницы, чтобы помочь восстановить нужную политику, поэтому режим аудита нельзя использовать с недоверенным кодом.
Какие бэкенды контейнеров используются на каждой ОС?Windows по умолчанию использует ProcessContainer с экспериментальными альтернативами вроде Windows Sandbox, WSLC, MicroVM, Hyperlight и IsolationSession; Linux по умолчанию использует Bubblewrap с вариантами LXC, MicroVM и Hyperlight; macOS использует Seatbelt.
Отправляет ли MXC телеметрию о том, что я запускаю?Официальные сборки Microsoft могут отправлять необязательную диагностическую телеметрию, но она отключена, если не выполнены все условия: запуск явно её разрешил, пользователь дал согласие, политика администратора это допускает и приложение её включило; локальные open-source сборки не направляют телеметрию в Microsoft, а на платформах, отличных от Windows, это пустая операция (no-op).
Какие SDK предоставляет MXC?MXC поставляет SDK для Rust, .NET и Node с версионированными API для разового выполнения и выполнения с учётом состояния; пакеты Node и .NET включают нативные ресурсы среды выполнения.
Контейнеры могут сохранять состояние или только выполняться один раз?MXC поддерживает управление жизненным циклом с учётом состояния: можно создавать, запускать, выполнять, останавливать и удалять постоянные контейнеры, а не только разовые запуски.
Какие политики можно задать для изолированной нагрузки?Политики охватывают доступ к файловой системе (только чтение, чтение-запись, запрещённые пути), доступ к сети (прокси, контроль исходящих соединений, фильтрация хостов) и доступ к интерфейсу (буфер обмена, экран, элементы GUI).
Зачем мне MXC, если можно просто запустить недоверенный код напрямую?MXC создан специально для изоляции недоверенного кода, такого как вывод LLM/моделей, плагины и инструменты, чтобы некорректная или вредоносная нагрузка не могла получить доступ к файлам, сети или интерфейсу, если это явно не разрешено.
What are similar projects?OpenShell, wasmer, cynative, dotnet-docker, dotnet-framework-docker, pulumi, copilot-sdk, SPACE
Which topics is it in?windows-tweaker, microsoft, containers, dotnet, sandbox, cybersecurity, kubernetes, sdk, rust, privacy, security, api
Creator
microsoft
Size
36.9 MB
Stars
2.9K
Updated
CommitOct 16Releasev1.0.1Oct 17
Age
8mo
Commits · 90 Days