Audience: MXC consumers
Public entrypoint: Microsoft.Mxc.Sdk.V1. Types | Overview
Signatures describe the typed consumer API and omit implementation bodies. Callers do not supply JSON or a schema version.
| Output | Create and run a container (MxcContainer) |
Run in an existing container (MxcLifecycle) |
Result |
|---|---|---|---|
| Capture stdout and stderr | Run / RunAsync |
RunInContainer / RunInContainerAsync |
ExecutionResult |
| Live standard pipes | Spawn / SpawnAsync |
SpawnInContainer / SpawnInContainerAsync |
MxcProcess |
| Interactive terminal | SpawnWithPty |
SpawnInContainerWithPty |
MxcPtyProcess |
Creation takes ContainerRequest and operation options. Existing-container
execution takes the ContainerId returned by provision, ExecutionRequest,
and operation options. Create-and-run PTY support covers IsolationSession, Bubblewrap,
LXC, and Seatbelt direct execution. Existing-container PTY support remains
IsolationSession-only. Seatbelt PTY rejects guiAccess and legacy
launchMethod: "open". Terminal handles
give the caller explicit input, output, resize, and process ownership; there
is no separate public attached-console launch API or API accepting "MXC request JSON".
| Operation | Use it to |
|---|---|
MxcPlatform.GetPlatformSupport |
Check whether the SDK can launch on this host and which backends it supports. |
MxcPlatform.GetAvailableBackends |
Discover native host-available backends, capabilities, tiers, and warnings. Availability is advisory; not every reported backend has a V1 creation API. |
MxcContainer.Probe (Windows) |
Evaluate an optional ProcessContainer request, including the isolation tier and request-specific compatibility diagnostics, without creating a container. |
MxcLifecycle.Validate* |
Perform native dry-run validation for a typed lifecycle operation without provisioning, starting, executing, stopping, or deprovisioning a container. |
Validation returns ValidationResult with warnings, not execution output.
It does not guarantee that a later operation will succeed on a changed host.
Equality operator.
public static bool operator ==(ContainerId left, ContainerId right);Inequality operator.
public static bool operator !=(ContainerId left, ContainerId right);Discover existing tool and SDK directories from PATH and well-known environment variables.
public static FilesystemPolicyResult GetAvailableToolsPolicy(
IReadOnlyDictionary<string, string?>? environment = null);Discover standard per-user application directories that should be granted read-only access.
public static FilesystemPolicyResult GetUserProfilePolicy(
IReadOnlyDictionary<string, string?>? environment = null);Discover the host temporary directory as a read-write policy fragment.
public static FilesystemPolicyResult GetTemporaryFilesPolicy(
IReadOnlyDictionary<string, string?>? environment = null);Probe which Windows ProcessContainer tier can serve a request.
public static ProbeOutput Probe(ContainerRequest? request = null);Run a container request to completion.
public static ExecutionResult Run(ContainerRequest request, RunOptions? options = null);Run a complete request asynchronously and capture its output.
Cancellation stops awaiting the result, not native execution. Use the request timeout to bound execution.
public static Task<ExecutionResult> RunAsync(
ContainerRequest request,
RunOptions? options = null,
CancellationToken cancellationToken = default);Spawn a container request and return its live process handle.
public static MxcProcess Spawn(ContainerRequest request, SpawnOptions? options = null);Spawn a complete request asynchronously with live standard streams.
public static Task<MxcProcess> SpawnAsync(
ContainerRequest request,
SpawnOptions? options = null,
CancellationToken cancellationToken = default);Spawn a complete request attached to an MXC-owned PTY.
public static MxcPtyProcess SpawnWithPty(
ContainerRequest request,
SpawnWithPtyOptions? options = null);Provision a new container.
public static ProvisionResult ProvisionContainer(
ProvisionRequest request,
ProvisionOptions? options = null);Parse and validate a provision request without allocating a container.
public static ValidationResult ValidateProvision(
ProvisionRequest request,
ProvisionOptions? options = null);Start a provisioned container.
public static LifecycleResult StartContainer(ContainerId id, StartOptions? options = null);Validate a start request without starting the container.
public static ValidationResult ValidateStart(ContainerId id, StartOptions? options = null);Run a command in a started container and return live stdio streams.
public static MxcProcess SpawnInContainer(
ContainerId id,
ExecutionRequest request,
SpawnInContainerOptions? options = null);Spawn a command asynchronously and return live stdio streams.
public static Task<MxcProcess> SpawnInContainerAsync(
ContainerId id,
ExecutionRequest request,
SpawnInContainerOptions? options = null,
CancellationToken cancellationToken = default);Run a command in a started container and attach it to a caller-resized PTY.
public static MxcPtyProcess SpawnInContainerWithPty(
ContainerId id,
ExecutionRequest request,
SpawnInContainerWithPtyOptions? options = null);Validate an execution request without starting a process.
public static ValidationResult ValidateProcess(
ContainerId id,
ExecutionRequest request,
SpawnInContainerOptions? options = null);Run an execution request to completion and capture its output.
public static Task<ExecutionResult> RunInContainerAsync(
ContainerId id,
ExecutionRequest request,
RunInContainerOptions? options = null,
CancellationToken cancellationToken = default);Run an ExecutionRequest synchronously and capture its output.
public static ExecutionResult RunInContainer(
ContainerId id,
ExecutionRequest request,
RunInContainerOptions? options = null);Stop a running container.
public static LifecycleResult StopContainer(ContainerId id, StopOptions? options = null);Validate a stop request without stopping the container.
public static ValidationResult ValidateStop(ContainerId id, StopOptions? options = null);Destroy a container and release its resources.
public static LifecycleResult DeprovisionContainer(
ContainerId id,
DeprovisionOptions? options = null);Validate a deprovision request without destroying the container.
public static ValidationResult ValidateDeprovision(
ContainerId id,
DeprovisionOptions? options = null);Probe every containment backend the current host can run.
public static IReadOnlyList<AvailableBackend> GetAvailableBackends();Probe whether the public SDK can launch containers on this host and which backends it can launch.
public static PlatformSupport GetPlatformSupport();The default 24-row by 80-column terminal.
public static MxcPtySize Default { get; } = new(24, 80);Read effective telemetry consent.
public static TelemetryConsentState GetConsent();Whether the host should show the first-run consent prompt.
public static bool NeedsConsentPrompt();Read the administrative telemetry policy.
public static TelemetryPolicyState GetPolicy();Request consent through a synchronous host presenter.
public static TelemetryConsentOutcome RequestConsent(
Func<TelemetryConsentPrompt, TelemetryConsentDecision> presenter,
string? locale = null);Request consent through an asynchronous host presenter.
public static Task<TelemetryConsentOutcome> RequestConsentAsync(
Func<TelemetryConsentPrompt, ValueTask<TelemetryConsentDecision>> presenter,
string? locale = null,
CancellationToken cancellationToken = default);Read stored/effective consent and the administrative ceiling.
public static TelemetryConsentStatus GetConsentStatus();Idempotently withdraw telemetry consent.
public static TelemetryConsentOutcome WithdrawConsent();