[LXC] State-aware sandbox lifecycle

[Darren Hoehna (dhoehna)]

Problem

LXC only runs one-shot. A caller hands it a config, it builds a container, runs a single workload, and destroys the container. Driving several commands against the same environment costs a full container build and teardown every time, and nothing the first command leaves behind is there for the second.

Fix

LXC implements the state-aware lifecycle: provision, start, exec, stop, and deprovision. A caller builds a container once, execs against it as many times as needed, and tears it down when finished.

• The state-aware surface requires the experimental opt-in, joining the three backends already behind it. Without --experimental the request is refused and the message names the flag. One-shot LXC is untouched and still needs no flag.
• Two callers racing to start the same container can no longer both bring it up. Starts are serialized per container.
• Where the request asks for a firewall, policy is enforced on traffic in both directions rather than outbound only.
• Enforcement follows the schema the request declares. A 0.8 directional config always enforces. A 0.7 config enforces only where enforcementMode asked for it, which leaves a config written before that field behaving as it always did.
• The Node SDK exposes lxc as a state-aware backend with per-phase config types, and sends 0.8.0-alpha.

🔍 Validation

Measured on ec0ba3a3:

• run_lxc_all_tests.sh against a live LXC host — 31 passed, 0 failed, 0 skipped, 1 disabled.
• cargo test -p lxc_common -p bwrap_common on Linux — 829 passed, 0 failed.
• cargo test -p wxc_common -p mxc_engine on Windows — 1,150 passed, 0 failed.
• npm test in sdk/node — 317 passed, 0 failed; tsc --noEmit clean.
• The generated schema and wire.ts regenerate byte-identical to what is committed.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes

📋 Issue Type

• Bug fix
• Feature
• Task

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Pull request overview

Copilot reviewed 76 out of 78 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

src/core/wxc_common/src/wire.rs:590

• The rolling wire model adds state-aware LXC, but the exact development contract was not updated: mxc_config_contract/src/dev/state_aware/provision/containment.rs does not recognize lxc, and provision/mod.rs has no LXC request variant. Consequently a valid 0.9 LXC lifecycle request accepted here diverges from the exact 0.9 contract/shadow parser. Add the closed LXC provision contract and regenerate its schema/types alongside this field.
  src/core/mxc_pty/src/lib.rs:416
• Abandoning this reader permanently leaks its thread and PTY descriptor when an escaped descendant keeps the secondary open. That is bounded for the CLI, but repeated timed-out calls from the in-process Rust/C#/FFI surfaces can exhaust host threads or file descriptors. Make the reader cancellable (for example via nonblocking polling plus a cancellation signal) and join it before returning instead of detaching it.

[Copilot]

Pull request overview

Copilot reviewed 76 out of 78 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24

• The C# surface now advertises Lxc, but it cannot build a valid LXC provision request. ValidateProvisionOptions accepts only null for this enum value, and BuildProvisionEnvelope has no LXC arm to emit the required experimental.lxc.provision.distribution and release, so every C# provision attempt reaches native code malformed. Add LXC-specific provision/start option types and serialize their required image and start policies before exposing this enum value.

    /// <summary>Linux container managed by LXC.</summary>
    Lxc,

src/core/wxc_common/src/wire.rs:590

• Only the rolling wire model is extended here. The supported 0.9.0-alpha exact state-aware contract still has no LXC containment/provision variant, and the dev adapter only adds lxc: None fillers. Consequently a version that is documented as being above the 0.8 floor cannot round-trip through the exact contract. Add the LXC provision contract and adapter arm, then regenerate the exact 0.9 schema/types alongside the rolling artifacts.
  tests/scripts/run_lxc_state_aware_test.sh:172
• This condition accepts any fast nonzero failure as proof of a timeout—for example, an attach error or missing command passes in under 25 seconds. Capture the output and require the timeout diagnostic so the test cannot go green without reaching the timeout path.
  docs/lxc-support/lxc-backend.md:349
• The removed constraint still applies to pre-0.8 one-shot requests: installs_firewall consults enforcementMode for legacy schemas, and LxcRunner still rejects a proxy under capabilities mode. As written, this section tells users that credentials are the only constraint even though a legacy proxy without firewall/both still fails at runtime.

One further constraint is enforced at parse time:

[Copilot]

Pull request overview

Copilot reviewed 76 out of 78 changed files in this pull request and generated 2 comments.

Suppressed comments (1)

src/core/wxc_common/src/config_contract_adapters/dev/state_aware.rs:57

• Hard-coding lxc: None leaves the exact 0.9.0-alpha state-aware contract without the LXC provision shape, even though this PR documents support for schema 0.8.0 or later. The rolling parser can accept experimental.lxc.provision, but the per-version parser cannot converge and will reject/drop it when exact dispatch becomes authoritative. Per the versioned-contract pattern used in this directory, add the closed LXC provision request/experimental types and adapter arm, then regenerate the exact schema and TypeScript oracle.

[Copilot]

Pull request overview

Copilot reviewed 76 out of 78 changed files in this pull request and generated no new comments.

Suppressed comments (5)

Previously missed (2) — in code that hasn't changed since the last review.

sdk/dotnet/Microsoft.Mxc.Sdk/MxcLifecycle.cs:395

• Routing LXC through the managed lifecycle also exposes ExecInSandbox and ExecInSandboxAsync, but both call the native streaming mxc_state_aware_exec entry point. The engine explicitly rejects LXC there because LXC implements lifecycle exec only, not SandboxProcess streaming, so these primary .NET exec APIs always return unsupported_phase for an LXC ID; only ExecInSandboxAttached can work. Either implement LXC streaming exec or expose an LXC-compatible run-to-completion path and reject unsupported methods before advertising full managed lifecycle support.

        StateAwareContainment.Lxc => LxcContainment,

src/backends/lxc/common/src/state_aware.rs:914

• A failed lxc-create can leave a partially defined container, but this path returns without cleanup and without returning the minted container name. For auto-generated names the caller then has no identifier with which to deprovision the leaked resource. Track creation ownership and perform safe best-effort cleanup on failure; at minimum include the container name in the error so an operator can recover it.

sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24

• Adding Lxc to the managed registry exposes ProvisionSandbox(StateAwareContainment.Lxc, ...), but the managed API cannot build a valid LXC provision request. There is no LxcProvisionOptions; null options emit no required experimental.lxc.provision object, while ValidateProvisionOptions rejects every existing non-null option type for LXC. Consequently every .NET LXC provision attempt fails before or during native validation. Add a typed LXC provision options class (including distribution/release and optional containerId), serialize it in BuildProvisionEnvelope, and accept it in validation.

    /// <summary>Linux container managed by LXC.</summary>
    Lxc,

src/core/wxc_common/src/wire.rs:590

• The new rolling wire field is missing from the exact 0.9.0-alpha contract. mxc_config_contract::dev::state_aware::Containment and ProvisionRequest have no LXC variant, parse_provision has no LXC branch, and the dev adapter hardcodes lxc: None; therefore the exact schema/types reject an LXC lifecycle request that the rolling model accepts. Add the LXC provision contract and adapter, then regenerate the exact 0.9.0-alpha schema and TypeScript oracle as well as the rolling artifacts.
  src/backends/lxc/common/src/state_aware.rs:1043
• This does not provide enforceable ingress isolation against the sandboxed workload. The chain is installed inside the container's own network namespace, while LXC exec runs as container root with CAP_NET_ADMIN, so contained code can flush or delete the INPUT chain and reopen inbound access immediately. Do not report ingress.default: deny as enforced unless the filter is moved to host-owned state or the workload is prevented from modifying netfilter (for example by dropping the relevant capability).

[Copilot]

Pull request overview

Copilot reviewed 76 out of 78 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

tests/scripts/run_lxc_experimental_provision_fields_test.sh:205

• This assertion contradicts the script's stated ability to run without an LXC runtime. On such a host the well-formed request stops at the availability check with backend_unavailable, not backend_error, so the test fails even though field validation behaved correctly. Either require/skip when LXC is absent if backend-error mapping is part of this test, or accept backend_unavailable here while still rejecting the field-validation diagnostics.

sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24

• Adding this enum value exposes ProvisionSandbox(StateAwareContainment.Lxc), but the managed API has no LXC provision options and BuildProvisionEnvelope has no LXC case. Consequently it can never serialize the required experimental.lxc.provision.distribution and release, so every .NET LXC provision call is rejected. Add the LXC-specific provision/start option types and envelope serialization before advertising this backend, or leave LXC out of the enum.

    /// <summary>Linux container managed by LXC.</summary>
    Lxc,

[Copilot]

🟡 Changes recommended

The .NET API is incomplete, exact-version contracts diverge, and LXC exec timeout isolation remains bypassable.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24

• Adding Lxc here exposes it as a usable .NET lifecycle backend, but the .NET surface cannot build a valid LXC request. There is no LxcProvisionOptions, BuildProvisionEnvelope has no LXC arm to emit the required experimental.lxc.provision.{distribution,release}, and ValidateProvisionOptions accepts null; consequently ProvisionSandbox(StateAwareContainment.Lxc) always reaches Rust without the required fields and fails as malformed_request. The start API also only accepts StateAwarePhaseOptions, so .NET callers cannot supply the filesystem/network policy that LXC applies at start. Add backend-specific provision/start option types and envelope serialization (plus typed metadata) before registering this enum value.

    Lxc,

sdk/node/src/state-aware.ts:169

• This channel assumption is already false for the new LXC path. LxcStateAwareRunner::exec relays workload output to stdout before returning, and a late failure such as timeout then appends the error envelope to that same stream; the added test at state-aware.test.ts:464-489 confirms tryParseErrorEnvelope(stdout) fails and the SDK resolves an ExecResult instead of throwing the documented typed MxcError. Please use a framing/separate-channel mechanism for dispatch failures (or otherwise make late failures unambiguous) rather than documenting stdout as envelope-only.

    // The cross-backend contract (§7.3) reserves stdout for the response
    // envelope in every phase, so a dispatch failure is always found there and
    // no backend needs its own channel rule.

src/core/wxc_common/src/wire.rs:590

• The new rolling wire field is not represented in the per-version 0.9.0-alpha contract. mxc_config_contract/src/dev/state_aware/provision/mod.rs still has only IsolationSession/WindowsSandbox/WSLC provision variants, and the dev adapter explicitly sets lxc: None; the exact schema and generated exact SDK oracle therefore also omit state-aware LXC. This leaves rolling and exact parsing inconsistent and will reject LXC when exact dispatch becomes authoritative. Add the closed LXC provision contract, adapter, exact-contract tests, and regenerate the 0.9.0-alpha schema/types alongside this wire change.

• Files reviewed: 89/91 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Network enforcement remains bypassable, while managed SDK and schema contracts are incomplete.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (6)

Previously missed (1) — in code that hasn't changed since the last review.

sdk/node/src/state-aware-types.ts:129

• This statement conflicts with the new lifecycle-wide schema floor: an explicit pre-0.8 LXC version is rejected before the start policy is evaluated, so it does not merely record these fields and skip the firewall. Document the rejection instead.

src/backends/lxc/common/src/network_ingress.rs:509

• This rule only blocks the bridge gateway address, but hostLoopback: deny covers every container-to-host path. A container can address another IP assigned to the host (for example its LAN address); Linux locally delivers that packet to the host even though the destination is not the bridge gateway, so this OUTPUT rule does not match it. Enforce the deny in the host namespace using the veth plus a local-destination match (or enumerate all host addresses), otherwise the default 0.8 posture still exposes host services.
  src/backends/lxc/common/src/state_aware.rs:1043
• The ingress policy is not an enforcement boundary against the sandboxed workload. LXC exec runs as container root with CAP_NET_ADMIN, so contained code can flush the INPUT/OUTPUT rules installed in its own network namespace and restore inbound/host reachability. Move these controls to host-owned rules scoped to the host-side veth, or remove CAP_NET_ADMIN before advertising ingress enforcement.
  sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24
• This public enum value cannot actually provision an LXC sandbox. BuildProvisionEnvelope has no LXC options arm, ValidateProvisionOptions accepts (Lxc, null), and the resulting request omits the required experimental.lxc.provision.distribution/release, so Rust always returns malformed_request; there is also no start-options type for LXC filesystem/network policy. Add the LXC-specific option types and serialization, or do not expose/accept this backend in the managed lifecycle API.

    /// <summary>Linux container managed by LXC.</summary>
    Lxc,

src/core/wxc_common/src/wire.rs:590

• LXC was added only to the rolling wire model. The closed 0.9.0-alpha contract still omits LXC from its state-aware containment/provision unions, and the dev adapter hard-codes lxc: None; consequently the generated exact schema/types reject an LXC lifecycle request even though the backend accepts 0.9. Per the repository's dual-contract workflow, add the matching exact contract and adapter support and regenerate the exact artifacts.
  sdk/node/src/state-aware-helper.ts:23
• This introduces a backend-specific schema default outside the canonical version source. schemas/schema-version.json has no LXC state-aware entry, and check-schema-versions.js validates only the shared and WSLC defaults, so the new TypeScript and C# constants can drift independently. Add a canonical stateAwareLxc value and extend the drift gate to check both SDKs.

// LXC's network surface is the directional field set, which a pre-0.8 schema
// does not enforce.  On the shared default a policy would be accepted and no
// firewall installed.
export const LXC_STATE_AWARE_VERSION = '0.8.0-alpha';

• Files reviewed: 89/91 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

LXC is incomplete in the exact contract and .NET SDK, while timeout handling and legacy mount migration can produce incorrect or unsafe behavior.

Review details

Suppressed comments (4)

sdk/dotnet/Microsoft.Mxc.Sdk/StateAwareTypes.cs:24

• Adding Lxc to the public state-aware enum exposes a backend that the managed SDK cannot actually provision: there is no LxcProvisionOptions, BuildProvisionEnvelope has no LXC arm, and ValidateProvisionOptions accepts null for LXC. The resulting envelope omits the required experimental.lxc.provision.distribution and release, so every ProvisionSandbox(StateAwareContainment.Lxc) call is rejected. The start API also cannot carry LXC's filesystem/network policy. Please add the LXC-specific provision/start option types and serialization, or do not expose this enum value yet.

    /// <summary>Linux container managed by LXC.</summary>
    Lxc,

src/core/wxc_common/src/wire.rs:590

• The rolling wire model now accepts experimental.lxc, but the exact 0.9 contract still has only IsolationSession, Windows Sandbox, and WSLC provision variants, and this PR's exact adapter explicitly sets lxc: None. Thus a valid 0.9 LXC lifecycle request is accepted by today's parser but rejected by the future-authoritative exact parser. Update mxc_config_contract::dev, its adapter, and regenerated exact schema/TypeScript oracle together as required by the parser transition.
  src/backends/lxc/common/src/state_aware.rs:1146
• A timeout is converted here into backend_error after attach_run has already streamed workload output. lxc-exec then appends an error envelope to that same stdout, so execInSandboxAsync cannot parse the envelope and returns an ordinary nonzero ExecResult; the new SDK test explicitly characterizes this gap. This also contradicts the lifecycle contract, which says runtime timeouts surface as sentinel exec exit codes rather than typed wire errors. Preserve the timed-out process's sentinel exit status on the executor path instead of returning MxcError after output has begun.
  src/backends/lxc/common/src/filesystem_mounts.rs:215
• The replacement only recognizes mount entries carrying the new marker, but MXC versions before this change appended their own lxc.mount.entry lines without a marker. A preserved/adopted container first configured by an older binary therefore keeps those legacy MXC mounts forever; restarting it with a narrower policy still exposes the old host paths. Please provide a migration/ownership mechanism for pre-marker MXC entries rather than treating every unmarked entry as operator-owned.

    // Derive the whole mount set first, then commit it in one config rewrite.
    // liblxc accumulates `lxc.mount.entry` lines across restarts, so the
    // previous run's MXC mounts have to go; committing the replacement one
    // entry at a time meant a crash or a rejected path partway through left a
    // durable config matching no policy anyone wrote. Only MXC's own entries
    // are replaced -- baseline mounts the distribution template or the operator
    // placed in the config carry no marker and survive.

• Files reviewed: 93/95 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Contract-version, .NET provisioning, timeout signaling, compatibility, and failed-provision cleanup issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 93/95 changed files
• Comments generated: 2
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

Legacy mounts can retain removed filesystem access, and the exact-contract and C# integrations are incomplete.

Review details

Suppressed comments (4)

src/core/wxc_common/src/config_contract_adapters/dev/state_aware.rs:57

• The new LXC state-aware shape exists only in the rolling wire model; this adapter still hard-codes lxc: None, and the closed dev contract has no LXC provision variant. Consequently the generated exact 0.9 schema rejects a request that the current parser accepts, so switching exact dispatch to authority would break this feature. Add LXC to mxc_config_contract::dev and this adapter, then regenerate both exact artifacts as required by docs/versioning.md:204-214.
  sdk/dotnet/Microsoft.Mxc.Sdk/MxcLifecycle.cs:395
• This makes LXC publicly routable, but ValidateProvisionOptions accepts only null for LXC and BuildProvisionEnvelope has no LXC options arm. The resulting envelope therefore omits required experimental.lxc.provision.distribution and release, so every C# LXC provision call fails as malformed_request, with no API capable of supplying the fields. Add an LXC provision-options type, validate it, serialize its fields, and cover the envelope in the C# tests before exposing this enum case.

        StateAwareContainment.Lxc => LxcContainment,

sdk/node/src/state-aware-helper.ts:21

• This new backend-specific schema default is not represented in schemas/schema-version.json, and scripts/versioning/check-schema-versions.js validates only the shared and WSLC defaults. The new Node and C# LXC constants can therefore drift silently, contrary to the repository's canonical-version rule. Add a canonical LXC state-aware field and extend the sync gate (or derive this from an existing canonical field).

// LXC refuses any state-aware request below 0.8.
export const LXC_STATE_AWARE_VERSION = '0.8.0-alpha';

src/backends/lxc/common/src/filesystem_mounts.rs:317

• This replacement only removes entries preceded by the new # mxc-managed-mount marker. Containers preserved by earlier releases have MXC mounts appended without that marker (the removed code called set_config_item directly), so adopting/restarting one with a tighter policy leaves the old broad mount active alongside the new set. That can preserve filesystem access the caller explicitly removed. Add a safe legacy migration/refusal strategy before treating the marked rewrite as authoritative.

    container.replace_mxc_mount_entries(&entries)

• Files reviewed: 93/95 changed files
• Comments generated: 0 new
• Review effort level: Balanced