Microsoft.Mxc.Sdk.Nvx.Runtime 1.1.0

Prefix Reserved
dotnet add package Microsoft.Mxc.Sdk.Nvx.Runtime --version 1.1.0
                    
NuGet\Install-Package Microsoft.Mxc.Sdk.Nvx.Runtime -Version 1.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Microsoft.Mxc.Sdk.Nvx.Runtime" Version="1.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Microsoft.Mxc.Sdk.Nvx.Runtime" Version="1.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Microsoft.Mxc.Sdk.Nvx.Runtime" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Microsoft.Mxc.Sdk.Nvx.Runtime --version 1.1.0
                    
#r "nuget: Microsoft.Mxc.Sdk.Nvx.Runtime, 1.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Microsoft.Mxc.Sdk.Nvx.Runtime@1.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Microsoft.Mxc.Sdk.Nvx.Runtime&version=1.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Microsoft.Mxc.Sdk.Nvx.Runtime&version=1.1.0
                    
Install as a Cake Tool

Microsoft.Mxc.Sdk

Audience: MXC consumers

Microsoft.Mxc.Sdk provides .NET APIs for authoring and executing MXC container requests through the in-process native mxc_ffi library. The versioned public API is in Microsoft.Mxc.Sdk.V1. All request and policy types in this API use the SDK-selected contract version; callers do not select that version. See the consumer glossary for terminology.

Use Microsoft.Mxc.Sdk.V1.Dev for MXC request JSON with a caller-declared contract version and separate experimental backend authorization. W365 Dev JSON execution uses the native runtime and output-drain deadline, without a second SDK timeout that interrupts service completion.

Requirements

The SDK targets net8.0 and net10.0. Applications targeting .NET 8 or .NET 9 use the .NET 8 assembly; applications targeting .NET 10 use the .NET 10 assembly. The behavioral tests and Native AOT smoke test validate both .NET 8 and .NET 10. Samples and the console driver target .NET 10.

Building from source requires the .NET 10 SDK and the Rust toolchain selected by src/rust-toolchain.toml. The repository's global.json selects the latest installed stable .NET 10.0 SDK feature band. Framework-dependent applications require the runtime for their application target; self-contained applications include their runtime. Backend-specific operating-system requirements still apply.

MicroVM JSON requests

On Windows x64 with Windows Hypervisor Platform enabled, install the optional Microsoft.Mxc.Sdk.Nvx.Runtime package at the same version as the SDK. Then:

using Microsoft.Mxc.Sdk.V1.Dev;

var result = await MxcContainer.RunJsonAsync(
    """{"version":"1.1.0-alpha","containment":"microvm","microvm":{"image":"mcr.microsoft.com/azurelinux/base/core:3.0"},"process":{"commandLine":"echo hello","timeout":30000}}""",
    new JsonOptions { Experimental = true });
Console.WriteLine(result.Stdout);

Run to completion

using Microsoft.Mxc.Sdk.V1;

var request = new ContainerRequest("cmd /c echo hello")
{
    Filesystem = new FilesystemPolicy
    {
        ReadwritePaths = { @"C:\work" },
    },
    TimeoutMs = 30_000,
};

ExecutionResult output = await MxcContainer.RunAsync(request);
Console.WriteLine($"exit={output.ExitCode} stdout={output.Stdout}");

Use MxcContainer.Run / RunAsync for captured output. Cancelling RunAsync stops awaiting the result; native execution continues until completion or the request timeout.

Spawn with streaming output

using Microsoft.Mxc.Sdk.V1;

using var process = await MxcContainer.SpawnAsync(
    new ContainerRequest("cmd /c echo hello from container") { TimeoutMs = 30_000 });
Task stdout = process.StandardOutput is { } output
    ? output.CopyToAsync(Console.OpenStandardOutput()) : Task.CompletedTask;
Task stderr = process.StandardError is { } error
    ? error.CopyToAsync(Console.OpenStandardError()) : Task.CompletedTask;
WaitResult result = await process.WaitAsync();
await Task.WhenAll(stdout, stderr);
Console.WriteLine($"exit={result.ExitCode}");

Spawn / SpawnAsync return a live MxcProcess with separate stdin, stdout, and stderr streams, plus wait, termination, and disposal operations. On WSLC, StandardInput is writable; dispose it to give the command end-of-file. Waiting before taking it also gives the command end-of-file. Run / RunAsync give a WSLC command end-of-file. Shared filesystem, network, and UI restrictions are authored directly on ContainerRequest, alongside the selected backend configuration. The SDK selects the contract version; ContainerRequest does not accept a caller-selected schema version.

UiPolicy.Disable defaults to true; clipboard and input-injection permissions are authored separately.

ContainerRequest.Containment accepts the SDK-defined Containment choices. Select an SDK-owned nested choice such as Containment.Process (the default), Containment.ProcessContainer, or Containment.Wslc. Backend semantics are validated by the native engine.

Creation methods accept their own RunOptions, SpawnOptions, SpawnWithPtyOptions, or SpawnExtendedOptions after the request. Set SpawnWithPtyOptions.Size to choose initial dimensions; it defaults to 24 rows by 80 columns. Async cancellation tokens come last.

Spawn with a caller-controlled terminal

PTY execution supports IsolationSession on Windows with the native isolation_session feature enabled, Bubblewrap and LXC on Linux, and Seatbelt direct execution on macOS. IsolationSession requires explicit unrestricted networking because it cannot enforce network restrictions.

using System.Text;
using Microsoft.Mxc.Sdk.V1;

using var terminal = MxcContainer.SpawnWithPty(
    new ContainerRequest("cmd.exe")
    {
        Containment = new Containment.IsolationSession(),
        Network = new NetworkPolicy
        {
            Egress = new NetworkEgressPolicy { Default = NetworkAction.Allow },
            Ingress = new NetworkIngressPolicy
            {
                Default = NetworkAction.Allow,
                HostLoopback = NetworkAction.Allow,
            },
        },
        TimeoutMs = 30_000,
    },
    new SpawnWithPtyOptions { Size = new MxcPtySize(24, 80) });
Task output = terminal.Output.CopyToAsync(Console.OpenStandardOutput());
await terminal.Input.WriteAsync(
    Encoding.UTF8.GetBytes("echo hello from terminal\r\nexit\r\n"));
terminal.Input.Dispose();
WaitResult result = await terminal.WaitAsync();
await output;
Console.WriteLine($"exit={result.ExitCode}");

SpawnWithPty returns an MxcPtyProcess with merged terminal output and resizing support. Initial dimensions default to 24 rows by 80 columns. PTY stderr is merged into Output. Closing Input requests terminal EOF in canonical mode; raw-mode applications must use their own completion protocol. Seatbelt rejects PTY mode with guiAccess. Unsupported combinations are rejected before sandbox creation.

Spawn with the caller's own console

SpawnWithExtendedOptions takes extensible options; its default SpawnStdio.Pipes behaves like Spawn. With SpawnStdio.Inherit it attaches the workload to the calling process's standard input, output, and error, such as a console, pseudo-console, or pipes the caller already set up. MXC allocates no pipes or PTY, and the returned MxcProcess has no streams to take. ProcessContainer, Bubblewrap, and Seatbelt support inherited stdio.

using Microsoft.Mxc.Sdk.V1;

using var process = MxcContainer.SpawnWithExtendedOptions(
    new ContainerRequest("cmd.exe /c echo hello") { TimeoutMs = 30_000 },
    new SpawnExtendedOptions { Stdio = SpawnStdio.Inherit });
WaitResult result = process.Wait();

Lifecycle API

ProvisionResult.Metadata is an optional ProvisionMetadata value. For IsolationSession, pattern-match IsolationSessionProvisionMetadata to read the agent account and workspace details. WSLC returns no provision metadata. Native metadata is converted to these SDK-defined types; callers do not parse native result JSON.

MxcLifecycle provides typed provision, start, exec, stop, and deprovision operations. The provision result contains an opaque ContainerId; pass it to subsequent operations rather than parsing it.

using Microsoft.Mxc.Sdk.V1;

var provisioned = MxcLifecycle.ProvisionContainer(
    new IsolationSessionProvisionRequest(new NetworkPolicy
    {
        Egress = new NetworkEgressPolicy { Default = NetworkAction.Allow },
        Ingress = new NetworkIngressPolicy
        {
            Default = NetworkAction.Allow,
            HostLoopback = NetworkAction.Allow,
        },
    }));
ContainerId id = provisioned.ContainerId;

try
{
    MxcLifecycle.StartContainer(id);
    try
    {
        ExecutionResult output = await MxcLifecycle.RunInContainerAsync(
            id, new ExecutionRequest("echo hello from lifecycle") { TimeoutMs = 30_000 });
        Console.WriteLine(output.Stdout);
    }
    finally
    {
        MxcLifecycle.StopContainer(id);
    }
}
finally
{
    MxcLifecycle.DeprovisionContainer(id);
}

Use SpawnInContainer or SpawnInContainerAsync for live piped execution. On WSLC, StandardInput is writable; dispose it to give the command end-of-file. Waiting before taking it also gives the command end-of-file. RunInContainer / RunInContainerAsync give a WSLC command end-of-file. The asynchronous methods are convenience wrappers over native operations and support cancellation. Backend and phase-specific policy requirements are described in the IsolationSession and WSLC guides.

MxcLifecycle.SpawnInContainerWithPty(id, request, options?) starts an IsolationSession exec with a caller-controlled terminal and returns an MxcPtyProcess. Set SpawnInContainerWithPtyOptions.Size to choose initial dimensions; it defaults to 24 rows by 80 columns.

ExecutionRequest supplies the command, working directory, environment, timeout, telemetry, and runtime-only network settings to both RunInContainer and SpawnInContainer. Existing-container network settings cannot change provision policy:

var request = new ExecutionRequest("echo hello")
{
    Network = new ProcessNetworkPolicy
    {
        RuntimeConfig = new NetworkRuntimeConfig
        {
            NetworkProxy = "http://proxy.example:8080",
        },
    },
};

Provisioning uses the same FilesystemPolicy and NetworkPolicy authoring types as container creation; the selected backend determines what it enforces.

Provisioning takes an SDK-owned ProvisionRequest followed by optional ProvisionOptions. Start, stop, and deprovision use StartOptions, StopOptions, and DeprovisionOptions. Existing-container execution takes the identity, ExecutionRequest, and its own SpawnInContainerOptions, RunInContainerOptions, or SpawnInContainerWithPtyOptions; PTY initial dimensions are on that options object. Invocation telemetry overrides request telemetry when supplied.

ValidateProvision, ValidateStart, ValidateStop, ValidateDeprovision, and ValidateProcess perform native dry-run validation and return ValidationResult with policy and operational Warnings, not an execution result. They accept the corresponding operation options. Backend/platform discovery, errors, telemetry, and helpers are also in Microsoft.Mxc.Sdk.V1; no public SDK types remain outside it.

Public V1 types

Purpose .NET type
Creation workload and cross-backend restrictions ContainerRequest
Persistent container identity ContainerId
Persistent container provision input ProvisionRequest
Existing-container workload ExecutionRequest
Live process with standard pipes MxcProcess
Live process with a terminal MxcPtyProcess
Terminal dimensions MxcPtySize
Captured execution ExecutionResult
Terminal process outcome WaitResult

All types above are in Microsoft.Mxc.Sdk.V1. See the networking guide; for policy behavior and the SDK API reference for complete signatures and types.

Errors, warnings, and discovery

Native failures are surfaced as MxcException; inspect Code, Operation, NativeCode, and Remediation when available. Security and operational warnings are available on ExecutionResult.Warnings and MxcProcess.Warnings. Provision returns identity, optional typed metadata, and ProvisionResult.Warnings. Start, stop, and deprovision return LifecycleResult.Warnings. Omitted native warnings become an empty array; malformed warnings fail explicitly. When IsolationSession provision metadata is present, AgentUserName, AgentUserSid, and EphemeralWorkspacePath are required non-null strings.

MxcPlatform.GetPlatformSupport() reports whether the SDK can launch a sandbox on the current host. MxcPlatform.GetAvailableBackends() reports host backend capabilities; availability is advisory and launch-time validation still applies.

On Windows, ProcessContainer is reported only when native PSEC is available; other backends are detected independently. Available MicroVM support is reported for the development JSON APIs; typed V1 requests cannot select it. MxcContainer.Probe(request) checks request compatibility without creating a container. If native ProcessContainer cannot serve the request, Tier is null and Error explains why; Probes still contains host capability facts.

Creation telemetry is supplied through Telemetry on RunOptions, SpawnOptions, SpawnWithPtyOptions, or SpawnExtendedOptions, not on ContainerRequest. These preferences remain accepted but do not control the four Required events. On eligible Windows builds, all supported request contracts collect Required events regardless of omission, Enabled = false, consent, or policy. Consent-management APIs retain their stored-state behavior; they do not disable Required collection. See Telemetry.

Filesystem discovery helpers are on Microsoft.Mxc.Sdk.V1.Policy.Filesystem and return FilesystemPolicyResult from the same namespace. They take an optional environment dictionary; null snapshots the process environment and an empty dictionary remains empty. GetAvailableToolsPolicy discovers existing tool directories and excludes system-critical paths; it does not inspect ACLs. GetUserProfilePolicy uses the supplied environment, and GetTemporaryFilesPolicy returns existing temporary storage without creating directories.

Package and native library

The package includes the native runtime assets for supported platforms. Applications do not need to launch an MXC executor process. The governed build pipeline produces the publishable NuGet package; build.bat creates local architecture-specific packages under output\packages.

For API details, see the SDK API reference. Build and validation commands are in the pull request guide.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 101 11/15/2026