Audience: MXC consumers
These references describe the supported V1 SDK APIs: operation signatures, public types, fields, and containment choices. They complement the SDK READMEs and backend guides; they do not replace native policy validation or certify backend availability.
See the consumer glossary for terminology.
| SDK | Reference | Public entrypoint |
|---|---|---|
| Rust | V1 | mxc_sdk::v1 |
| .NET | V1 | Microsoft.Mxc.Sdk.V1 |
| Node | V1 | @microsoft/mxc-sdk/v1 |
| Task | Input | Result |
|---|---|---|
| Create and run a container | ContainerRequest, operation options |
Captured ExecutionResult or a live process |
| Provision a persistent container | ProvisionRequest, ProvisionOptions |
ProvisionResult with ContainerId and optional metadata |
| Start, stop, or deprovision | ContainerId, operation options |
LifecycleResult |
| Run in an existing container | ContainerId, ExecutionRequest, operation options |
Captured ExecutionResult or a live process |
| Validate a lifecycle operation | The operation's typed inputs | ValidationResult, without performing the operation |
Choose captured output, live standard pipes, or an interactive terminal using the launch tables for Rust, .NET, and Node. Requests describe the workload and policy; operation options control invocation behavior. PTY options include the initial size; resize is a method on the returned terminal process.
Results and live handles expose warnings and optional execution metadata. Provision metadata is backend-specific; each language's type reference lists the supported fields.
ContainerRequest selects containment and carries shared restrictions;
backend-specific settings use *Config types listed in each language's type
reference. Omitted environment input
uses backend defaults, whereas an explicitly empty environment is preserved.
Filesystem discovery helpers follow the same distinction for their host
environment input. Native validation decides which policies the backend can
enforce.
Invocation telemetry belongs to operation options and is always subject to persisted MXC consent and administrative restrictions.
Rust execution is synchronous. .NET and Node also expose asynchronous operations; their signature pages identify which have synchronous counterparts. .NET cancellation tokens are trailing parameters. Casing, constructors, enums, and discriminated unions follow each language's conventions.
Update the affected signature and type pages whenever a public SDK API changes. Review the corresponding APIs in all three SDKs, including options, defaults, nullability, ownership, platform gates, and examples.
Breaking changes to a published SDK API require a new versioned (V*) API
surface and matching signature/type references under each affected SDK's
docs/api-reference/<sdk>/v*/ directory. Preserve the published version's
references.