Audience: MXC consumers
Public entrypoint: mxc_sdk::v1. Types | Overview
Signatures describe the typed consumer API and omit implementation bodies. Callers do not supply JSON or a schema version. The separate V1.Dev exact-JSON API accepts caller-authored requests for create-and-run execution and container lifecycle operations. Attached execution in an existing container is not exposed by the V1 SDK.
| Output | Create and run a container | Run in an existing container | Result |
|---|---|---|---|
| Capture stdout and stderr | v1::run |
v1::container::run_in_container |
ExecutionResult |
| Live standard pipes | v1::spawn |
v1::container::spawn_in_container |
MxcProcess |
| Interactive terminal | v1::spawn_with_pty |
v1::container::spawn_in_container_with_pty |
MxcPtyProcess |
| The caller's own stdin, stdout, and stderr | v1::spawn_with_extended_options with SpawnStdio::Inherit |
— | MxcProcess |
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. A PTY gives the
caller explicit input, output, resize, and process ownership instead of
attaching the workload to the host process's global console streams.
Read the terminal output concurrently rather than only after wait. On macOS
a workload cannot exit while its terminal output is still unread, so a caller
that waits first without reading can block indefinitely.
spawn_with_extended_options takes extensible options. Its default
SpawnStdio::Pipes behaves exactly like spawn. SpawnStdio::Inherit
attaches the workload to whatever the calling process's stdin, stdout, and
stderr already are, such as a console, pseudo-console, or pipes the caller set
up. MXC allocates no pipes or PTY, so the caller keeps ownership of its
terminal handling. Inherit is supported by ProcessContainer, Bubblewrap, and
Seatbelt.
| Operation | Use it to |
|---|---|
platform_support |
Check whether the SDK can launch on this host and which backends it supports. |
available_backends |
Discover native host-available backends, capabilities, tiers, and warnings. Availability is advisory; not every reported backend has a V1 creation API. |
probe (Windows) |
Evaluate an optional ProcessContainer request, including the isolation tier and request-specific compatibility diagnostics, without creating a container. |
container::validate_* |
Perform native dry-run validation for a typed lifecycle operation without provisioning, starting, executing, stopping, or deprovisioning a container. |
Validation checks request structure, policy, and backend support. It returns
ValidationResult with warnings, not execution output, and does not guarantee
that a later operation will succeed on a changed host.
Probe the host and return only the backends it can currently run.
Availability is advisory; a later launch can fail if the host or runtime
changes. On Windows x64, MicroVM requires the microvm feature, a bundle
manifest and agent library, and an active hypervisor.
pub fn available_backends() -> Vec<AvailableBackend>;Discover tool and SDK directories from environment (defaults to the process environment) as read-only policy paths.
On Windows, finding pwsh.exe on PATH also grants read-write access to the
PSReadLine history directory under the supplied USERPROFILE. It does not
implicitly grant read access to a drive root.
For PowerShell startup failures, see troubleshooting.
pub fn available_tools_policy(environment: Option<&[(String, String)]>, options: ToolsPolicyOptions) -> FilesystemPolicyResult;Deprovision an existing container.
pub fn deprovision_container(
container_id: &ContainerId,
options: DeprovisionOptions,
) -> Result<LifecycleResult, Error>;Provision a container from typed Rust policy.
pub fn provision_container(
request: ProvisionRequest,
options: ProvisionOptions,
) -> Result<ProvisionResult, Error>;Spawn a workload in an existing container with a caller-controlled PTY.
pub fn spawn_in_container_with_pty(
container_id: &ContainerId,
request: ExecutionRequest,
options: SpawnInContainerWithPtyOptions,
) -> Result<MxcPtyProcess, Error>;Start an existing container.
pub fn start_container(container_id: &ContainerId, options: StartOptions) -> Result<LifecycleResult, Error>;Stop an existing container.
pub fn stop_container(container_id: &ContainerId, options: StopOptions) -> Result<LifecycleResult, Error>;Validate a deprovision request without changing the container.
pub fn validate_deprovision(
container_id: &ContainerId,
options: DeprovisionOptions,
) -> Result<ValidationResult, Error>;Validate an execution request without running a workload.
pub fn validate_process(
container_id: &ContainerId,
request: ExecutionRequest,
options: SpawnInContainerOptions,
) -> Result<ValidationResult, Error>;Validate a provision request without creating a container.
pub fn validate_provision(
request: ProvisionRequest,
options: ProvisionOptions,
) -> Result<ValidationResult, Error>;Validate a start request without starting the container.
pub fn validate_start(
container_id: &ContainerId,
options: StartOptions,
) -> Result<ValidationResult, Error>;Validate a stop request without stopping the container.
pub fn validate_stop(
container_id: &ContainerId,
options: StopOptions,
) -> Result<ValidationResult, Error>;Detect MXC support on the current host.
On Windows, ProcessContainer requires native PSEC support. Other supported backends are detected independently; the host is unsupported when none are available. MicroVM is reported when available, but execution requires the development JSON API; typed V1 requests cannot select it. Availability is advisory.
pub fn platform_support() -> PlatformSupport;Probe an optional ProcessContainer request without creating a container.
pub fn probe(request: Option<&ContainerRequest>) -> Result<crate::ProbeOutput, Error>;Run a [ContainerRequest] to completion and capture its output.
pub fn run(request: ContainerRequest, options: RunOptions) -> Result<ExecutionResult, Error>;Run a workload in an existing container to completion and capture output.
pub fn run_in_container(
container_id: &ContainerId,
request: ExecutionRequest,
options: RunInContainerOptions,
) -> Result<ExecutionResult, Error>;Spawn a [ContainerRequest] and return its live process. On WSLC,
MxcProcess::take_stdin returns a writable stdin. Close or drop it to give the
workload end-of-file. Waiting closes an untaken stdin.
pub fn spawn(request: ContainerRequest, options: SpawnOptions) -> Result<MxcProcess, Error>;Spawn a workload in an existing container and return its live process. On WSLC,
MxcProcess::take_stdin returns a writable stdin. Close or drop it to give the
workload end-of-file. Waiting closes an untaken stdin. Killing a WSLC process
that is still running, or reaching its timeout, deletes its container about a
minute later, because MXC does not signal a WSLC process that has stdin.
pub fn spawn_in_container(
container_id: &ContainerId,
request: ExecutionRequest,
options: SpawnInContainerOptions,
) -> Result<MxcProcess, Error>;Spawn a [ContainerRequest] attached to a caller-controlled PTY.
pub fn spawn_with_pty(
request: ContainerRequest,
options: SpawnWithPtyOptions,
) -> Result<MxcPtyProcess, Error>;Spawn a [ContainerRequest] with stdio and other controls chosen in SpawnExtendedOptions.
With SpawnStdio::Inherit the returned MxcProcess has no streams to take;
use it to wait for or kill the process. Backends other than ProcessContainer,
Bubblewrap, and Seatbelt reject Inherit with ErrorCode::UnsupportedContainment.
pub fn spawn_with_extended_options(
request: ContainerRequest,
options: SpawnExtendedOptions,
) -> Result<MxcProcess, Error>;Return effective optional-telemetry consent. This state and consent-management operations do not control Required collection for supported contracts. See Telemetry.
pub fn get_consent() -> ConsentState;Read stored and effective consent.
pub fn get_consent_status() -> ConsentStatus;Read the administrative telemetry policy.
pub fn get_policy() -> PolicyState;Whether an administrator has blocked telemetry on this machine.
pub fn is_blocked_by_policy() -> bool;Whether a host should show the first-run consent prompt.
pub fn needs_consent_prompt() -> bool;Invoke a host presenter and persist its decision.
pub fn request_consent<F>(
locale: Option<&str>,
presenter: F,
) -> Result<ConsentActionOutcome, ConsentError>
where
F: FnOnce(&ConsentPrompt) -> Result<ConsentDecision, String>;Asynchronous counterpart to [request_consent].
pub async fn request_consent_async<F, Fut>(
locale: Option<&str>,
presenter: F,
) -> Result<ConsentActionOutcome, ConsentError>
where
F: FnOnce(ConsentPrompt) -> Fut,
Fut: std::future::Future<Output = Result<ConsentDecision, String>>;Idempotently withdraw telemetry consent.
pub fn withdraw_consent() -> Result<ConsentActionOutcome, ConsentError>;Read-write policy for the host temporary directory.
pub fn temporary_files_policy(environment: Option<&[(String, String)]>) -> FilesystemPolicyResult;Read-only policy for standard user-profile application data locations.
pub fn user_profile_policy(environment: Option<&[(String, String)]>) -> FilesystemPolicyResult;