Audience: MXC consumers
Companion to the lifecycle architecture and native JSON format. See the consumer glossary for terminology.
MXC separates container creation from persistent lifecycle operations.
Creation runs a ContainerRequest. With manual lifecycle operations, the caller
provisions a container, starts it, runs ExecutionRequest workloads, then stops
and deprovisions it. The public SDK API is versioned independently of the
native JSON request and response format.
All public types, operations, probes, backend/platform discovery, telemetry,
and helpers live under mxc_sdk::v1, Microsoft.Mxc.Sdk.V1, or
@microsoft/mxc-sdk/v1. The Node package root exports no APIs.
| Capability | Rust | .NET | Node |
|---|---|---|---|
| Creation input | ContainerRequest |
ContainerRequest |
ContainerRequest |
| Captured creation | run |
MxcContainer.Run / RunAsync |
run |
| Live standard pipes | spawn |
MxcContainer.Spawn / SpawnAsync |
spawn |
| Provision | container::provision_container |
MxcLifecycle.ProvisionContainer |
provisionContainer |
| Start | container::start_container |
MxcLifecycle.StartContainer |
startContainer |
| Existing-container capture | container::run_in_container |
RunInContainer / RunInContainerAsync |
runInContainer |
| Existing-container streaming | container::spawn_in_container |
SpawnInContainer / SpawnInContainerAsync |
spawnInContainer |
| Stop | container::stop_container |
MxcLifecycle.StopContainer |
stopContainer |
| Deprovision | container::deprovision_container |
MxcLifecycle.DeprovisionContainer |
deprovisionContainer |
- Creation takes
ContainerRequestfollowed by its operation-specific options. - Provision takes
ProvisionRequestfollowed byProvisionOptions. - Start, stop, and deprovision take
ContainerIdfollowed by their own options. - Existing-container execution takes
ContainerId,ExecutionRequest, and its execution-specific options. Initial PTY size is a field of those options. - .NET asynchronous cancellation tokens are last. Rust remains synchronous.
Common process settings are command, working directory, environment,
inherit-default-environment, and timeout. SDKs use properties or setters
according to their language conventions. Supported containment choices are defined by
Rust enum variants, SDK-owned .NET subclasses, and Node discriminated unions.
Creation defaults to generic Process intent.
Explicit PTY APIs return SDK-owned terminal process handles with interactive input, resize, wait, termination, and disposal. Use these for interactive workloads instead of attaching a workload to the host application's console. See the launch-choice tables for Rust, .NET, and Node.
Explicit validation APIs perform native dry-run validation and return no execution result. Backend policy and feature support remain native-engine responsibilities. Invocation telemetry cannot grant persisted consent or override restrictive administrative policy.
| Phase | Valid from state | Resulting state | Output |
|---|---|---|---|
provision |
Not provisioned | Provisioned | Opaque identity and optional metadata |
start |
Provisioned | Running | Optional metadata |
exec |
Running | Running | Live streams or captured execution output |
stop |
Running | Provisioned | Optional metadata |
deprovision |
Provisioned | Not provisioned | Optional metadata |
Provision returns an opaque ContainerId. Keep that value and pass it unchanged
to start, execution, stop, and deprovision. Do not parse or construct it from
the optional, caller-selected label on a creation request.
Backend-specific policy, idempotence, concurrency, cleanup, and error mapping are documented in the backend guides. SDKs surface structured errors and warnings rather than converting failures into successful-looking output.
The full design documents engine dispatch, backend interfaces, and native JSON contracts for contributors and direct executor/FFI integrations. These implementation details are not required to author typed SDK requests.