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. JSON request adapters are not part of the supported V1 API. Attached execution 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 |
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". 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.
| 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.
pub fn available_backends() -> Vec<AvailableBackend>;Discover tool and SDK directories from environment (defaults to the process environment) as read-only policy paths.
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.
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.
pub fn spawn(request: ContainerRequest, options: SpawnOptions) -> Result<MxcProcess, Error>;Spawn a workload in an existing container and return its live process.
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>;Return the consent state currently effective for telemetry authorization.
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;