[LXC] State-aware sandbox lifecycle

.azure-pipelines/templates/SDK.Integration.Test.Job.yml

@@ -102,6 +102,20 @@ jobs:
             sudo apt-get install -y -qq lxc lxc-utils dnsmasq-base iptables bubblewrap slirp4netns
           displayName: Install LXC, Bubblewrap, and slirp4netns
 
+        # LXC enforces network policy from the policy itself, and the default is
+        # deny-all, so every LXC run installs an egress chain even when the
+        # request carries no network section.  A bridged veth only reaches
+        # FORWARD while br_netfilter delivers bridged packets to iptables, and
+        # without it the backend refuses to report success for a policy it
+        # cannot enforce.  Tolerated rather than required, because a hosted pool
+        # may forbid loading modules; when it does, the LXC tests fail exactly
+        # as they already would.
+        - script: |
+            sudo modprobe br_netfilter || echo "br_netfilter unavailable; LXC policy enforcement is unreachable on this pool"
+            sudo sysctl -w net.bridge.bridge-nf-call-iptables=1 || true
+            sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=1 || true
+          displayName: Enable bridge netfilter
+
         - script: sudo MXC_SKIP_LXC_NETWORK_TESTS=1 MXC_DEBUG=${{ parameters.debug }} npm test
           workingDirectory: $(integrationDirectory)
           displayName: npm test (sudo, with LXC)

.github/workflows/SDK.Integration.Test.Job.yml

@@ -180,6 +180,21 @@ jobs:
           sudo systemctl start lxc-net
           sudo systemctl is-active --quiet lxc-net
 
+      # LXC enforces network policy from the policy itself, and the default is
+      # deny-all, so every LXC run installs an egress chain even when the
+      # request carries no network section.  A bridged veth only reaches
+      # FORWARD while br_netfilter delivers bridged packets to iptables, and
+      # without it the backend refuses to report success for a policy it cannot
+      # enforce, so every LXC test fails at the backend probe.
+      - name: Enable bridge netfilter
+        if: matrix.os_label == 'linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo modprobe br_netfilter
+          sudo sysctl -w net.bridge.bridge-nf-call-iptables=1
+          sudo sysctl -w net.bridge.bridge-nf-call-ip6tables=1
+
       - name: Restore execute permission on mxc-exec-mac
         if: matrix.os_label == 'macos'
         shell: bash

docs/lxc-support/lxc-backend.md

@@ -82,6 +82,49 @@ The `distribution` and `release` fields control which LXC template is used to cr
 | `debian` | `bookworm`, `trixie` | Stable, well-tested |
 | `fedora` | `39`, `40` | Modern packages |
 
+### State-aware lifecycle configuration
+
+The table above describes the **one-shot** surface, where the two fields sit in
+a top-level `lxc` section.  The state-aware lifecycle carries the same two
+fields in the backend's own sub-object instead, under
+`experimental.lxc.provision`, alongside the `provision` phase that consumes
+them:
+
+```json
+{
+    "phase": "provision",
+    "containment": "lxc",
+    "experimental": {
+        "lxc": {
+            "provision": {
+                "distribution": "alpine",
+                "release": "3.23"
+            }
+        }
+    }
+}
+```
+
+`provision` is the only phase that takes LXC-specific configuration.  `start`,
+`exec`, `stop`, and `deprovision` carry no `experimental.lxc` payload — they
+route by the `sandboxId` returned from `provision`, and their cross-cutting
+`filesystem` and `network` policy comes from the top-level sections.
+
+| Rule | Enforced by | Diagnostic when violated |
+|------|-------------|--------------------------|
+| Both `distribution` and `release` are required | runtime | `LXC distribution and release are required` |
+| `experimental.lxc.provision` must be present on the provision phase | runtime | `experimental.lxc.provision with distribution and release is required` |
+| Each field must be a string | schema and parser | ``Invalid configuration at `experimental.lxc.provision.distribution`: invalid type: ... expected a string`` |
+| Only one backend section may appear, and it must match `containment` | runtime | `Multiple containment backends configured: ... Only one backend section is allowed; remove the unused section(s)` |
+
+Both fields are optional in the wire model, exactly as they are in the one-shot
+`lxc` section, so the schema accepts a provision section that omits them and the
+backend is what refuses it.  That split is deliberate: the `experimental` block
+is intentionally permissive and the schema "is an editor/CI convenience, never
+the gate" (`docs/schema-codegen.md`), so requirements that a caller must satisfy
+live in the parser and the backend.  See `docs/versioning.md` for the
+single-backend-section rule and its graduation path.
+
 ### Process Environment and Working Directory
 
 The `process.cwd` and `process.env` fields from the standard schema are honored inside the container:
@@ -111,7 +154,12 @@ Filesystem policies are enforced via bind mounts in the container configuration:
 
 Network policy has two independent halves: outbound (egress) filtering on the host, described first, and inbound (ingress) filtering inside the container, described under [Inbound (ingress) policy](#inbound-ingress-policy).
 
-Both halves require `enforcementMode` to be `firewall` or `both`.  Under the default `capabilities` mode, MXC installs no iptables rules at all, so `defaultPolicy`, `allowedHosts`, and `blockedHosts` are parsed but never take effect.
+The egress half is installed whenever the policy requires firewall enforcement:
+`defaultPolicy` is `"block"` (including its default when omitted),
+`allowedHosts` or `blockedHosts` is non-empty, or `proxy` is enabled.  The
+ingress half is installed for every LXC run, regardless of that predicate.  LXC
+accepts `enforcementMode` but ignores its value; it does not disable policy
+enforcement.
 
 Outbound policies are enforced with parallel `iptables` and `ip6tables` chains scoped to the container's virtual ethernet (veth) interface:
 
@@ -220,13 +268,14 @@ Egress firewall state is torn down automatically with best-effort removal of the
 
 ### Inbound (ingress) policy
 
-Inbound filtering is a separate chain from the egress chains above, and it lives **inside the container's own network namespace** rather than on the host. Every command is issued through `nsenter -t <init-pid> -n`, so the container's init PID is mandatory. When a firewall enforcement mode is requested and MXC cannot discover that PID, the run is aborted rather than started with inbound enforcement silently disabled. This is LXC-specific, and the Bubblewrap comparison is policy-dependent rather than absolute: Bubblewrap gives the sandbox its own network namespace via `--unshare-net` when the default policy is `block` with no `allowedHosts`, no `blockedHosts`, and no proxy, and shares the host's namespace otherwise. It installs no inbound chain in either case — under `--unshare-net` because nothing outside the sandbox can reach in, and when the namespace is shared because an inbound chain there would be host-wide.
+Inbound filtering is a separate chain from the egress chains above, and it lives **inside the container's own network namespace** rather than on the host. Every command is issued through `nsenter -t <init-pid> -n`, so the container's init PID is mandatory for every run. If MXC cannot discover that PID, the run is aborted rather than started with inbound enforcement silently disabled. This is LXC-specific, and the Bubblewrap comparison is policy-dependent rather than absolute: Bubblewrap gives the sandbox its own network namespace via `--unshare-net` when the default policy is `block` with no `allowedHosts`, no `blockedHosts`, and no proxy, and shares the host's namespace otherwise. It installs no inbound chain in either case — under `--unshare-net` because nothing outside the sandbox can reach in, and when the namespace is shared because an inbound chain there would be host-wide.
 
 Every `iptables`/`ip6tables` subprocess is spawned with `LC_ALL=C` and `LANG=C`. Teardown decides whether a non-zero exit means "already absent" by matching iptables' own diagnostic text, and that text is localized, so an unpinned locale would turn a benign already-absent result on a non-English host into a fatal error and abort every fresh install.
 
-The rows below describe the `firewall` and `both` enforcement modes. `networkEnforcementMode` defaults to `capabilities`, and under that mode the ingress path installs nothing at all — the same gate that skips the egress chains skips this one, so inbound is unfiltered and `allowLocalNetwork: true` is accepted rather than refused. Inbound default-deny is a property of the firewall enforcement modes, not of every LXC run.
+The rows below apply to every LXC run.  Inbound default-deny is unconditional;
+it does not depend on the egress policy or `enforcementMode`.
 
-| Policy (`networkEnforcementMode`: `firewall` or `both`) | Implementation |
+| Network policy | Implementation |
 |--------|---------------|
 | `allowLocalNetwork: false` (default) | Container `INPUT` chain drops new inbound connections |
 | `allowLocalNetwork: true` | **Not yet implemented.** Firewall setup fails with an explicit not-yet-implemented error rather than falling back to an unenforced accept |
@@ -265,15 +314,8 @@ unreachable and the firewall rule would never match. `{ "builtinTestServer":
 true }` is rejected for the same reason, as is a `url` whose host is a loopback
 literal.
 
-Two further constraints are enforced at parse time, both rejections rather than
-silent corrections:
+One further constraint is enforced at parse time:
 
-- **`enforcementMode` must be `firewall` or `both`.** Under the default
-  `capabilities` mode no iptables rules are installed, so the proxy env vars
-  would be injected while direct egress stayed open — a config that reads as
-  deny-all-except-proxy and enforces neither half. MXC refuses it rather than
-  auto-promoting the mode, so a stated enforcement level is never silently
-  rewritten.
 - **The `url` must not carry credentials.** LXC passes the proxy URL to
   `lxc-attach` as a `--set-var` argument, and process arguments are
   world-readable through `/proc/<pid>/cmdline`, so inline `user:pass@` would be

docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md

@@ -236,14 +236,27 @@ wire format and have different roles:
 | Field | Where it appears | Source | Purpose |
 |---|---|---|---|
 | `sandboxId` | State-aware wire envelope (§7); SDK return value from `provisionSandbox` | System-generated by the backend | Opaque routing identifier; must be passed to subsequent state-aware calls |
-| `containerId` | One-shot wire envelope (per `docs/schema.md`) | Caller-supplied (or auto-generated random hex) | Human-readable label, used as e.g. AppContainer profile name |
+| `containerId` | One-shot wire envelope (per `docs/schema.md`); **LXC** state-aware `provision` | Caller-supplied (or auto-generated random hex) | Human-readable label, used as e.g. AppContainer profile name or LXC container name |
 
 State-aware non-provision calls carry `sandboxId` on the request; provision returns it
 on the response. A state-aware request **may** also carry `containerId` — the parser
 preserves it into the request the backend receives — but it is inert for backends that
 do not use it as a label, and it is never a routing key on the state-aware path.
 One-shot calls carry `containerId` (when present); they do not carry `sandboxId`.
 
+**LXC exception.** LXC is the one backend whose state-aware `provision` also accepts
+`containerId`, because its durable state *is* the named container and `lxc-ls` /
+`lxc-attach` address it by name. Consequences callers must understand:
+
+- The returned `sandboxId` is `lxc:<containerName>`, so the name is not opaque.
+- Provision is **adopt-or-create**: if a container with that name already exists it is
+  reused rather than created, and `provisionMetadata.created` reports which happened.
+- Deprovision **destroys the container unconditionally**, including one it adopted
+  rather than created. MXC retains no caller-side state between phases, so deprovision
+  cannot distinguish an adopted container from a created one. Callers that pass a
+  `containerId` for a pre-existing container therefore hand MXC ownership of it.
+- Omit `containerId` to get a generated name and avoid adopting anything.
+
 ## 6. TypeScript SDK
 
 The SDK adds five new functions, exported from `@microsoft/mxc-sdk` alongside the existing
@@ -1688,6 +1701,43 @@ unconditionally by the in-guest agent).
 | `network` | rejected | rejected | rejected | rejected | rejected |
 | `ui` | rejected | rejected | rejected | rejected | rejected |
 
+For LXC, filesystem path lists and `network` are applied at **start** — the container is
+created empty at provision and its mounts and iptables chain are installed just before
+it runs — and rejected at every other phase. Only a *non-empty* path list counts as a
+filesystem policy, so a `filesystem` block whose lists are all empty is accepted at any
+phase. `ui` is not consulted anywhere in the LXC backend; `LxcStartConfig` does not
+expose it, so SDK callers cannot pass it, but a raw-JSON caller that sends it is not
+rejected.
+
+| Field | provision | start | exec | stop | deprovision |
+|---|---|---|---|---|---|
+| `filesystem` (non-empty path lists) | rejected | applied | rejected | rejected | rejected |
+| `network` | rejected | applied | rejected | rejected | rejected |
+| `ui` | ignored | ignored | ignored | ignored | ignored |
+
+> **LXC `network` constraints.** `network.proxy` and `allowLocalNetwork` are
+> rejected at start.  LXC enforces network policy through iptables whenever
+> `defaultPolicy` is `"block"`, either host list is non-empty, or proxy is
+> enabled.  The value of `enforcementMode` is accepted but ignored by LXC; it
+> does not disable enforcement.  The veth is not discovered after start: the name
+> is derived from the container name and pinned by a container-global
+> `lxc.hook.start-host` installed before start, so the chain is scoped before the
+> interface exists. The hook resolves the container's peer interface from
+> `$LXC_PID` and renames it to that name; if it cannot find one it exits
+> nonzero, which aborts the start rather than leaving the container unfiltered.
+> The interface set comes from liblxc rather than from the container's own
+> config file, so an `lxc.include` that declares interfaces elsewhere is
+> resolved rather than guessed at, and no interface index is read at all — a
+> container numbering its only interface `lxc.net.3` is enforced exactly as one
+> using `lxc.net.0`, as is one at any index liblxc accepts. Start fails instead
+> when that pin cannot be trusted to cover the container's traffic — when the
+> container declares anything other than exactly one interface, or does not
+> declare that interface's type as `veth`. An undeclared type is refused
+> alongside a wrong one, because absence is not evidence of a veth, and a
+> `macvlan` or `phys` interface would take a hook pinned to a veth name that
+> never appears while its traffic ran unfiltered. `removeRulesOnExit` is not
+> part of the LXC surface (see `LxcNetworkConfig`).
+
 - **Compile-time enforcement at the SDK.** Each per-(backend, phase) Config (§6.1)
   declares only the cross-cutting fields the matrix marks as `applied` for that phase
   *and* that the runtime currently honors. TypeScript rejects callers passing fields

schemas/dev/mxc-config.schema.0.8.0-dev.json

@@ -201,6 +201,17 @@
           ],
           "description": "IsolationSession backend config (Windows)."
         },
+        "lxc": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/LxcExperimental"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "LXC backend config (Linux)."
+        },
         "seatbelt": {
           "anyOf": [
             {
@@ -401,6 +412,43 @@
       },
       "type": "object"
     },
+    "LxcExperimental": {
+      "description": "LXC backend config under the experimental surface. Carries only the per-phase state-aware nesting for the phases that take config (`provision`); the one-shot LXC surface is the stable top-level `lxc` section, so this type is named apart from it rather than shared with it. `start`, `exec`, `stop`, and `deprovision` take no per-phase config payload.",
+      "properties": {
+        "provision": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/LxcProvisionPhase"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "State-aware provision-phase configuration."
+        }
+      },
+      "type": "object"
+    },
+    "LxcProvisionPhase": {
+      "description": "Provision-phase LXC configuration (state-aware lifecycle), nested under `experimental.lxc.provision`. Names the container image to create.\n\nFilesystem mounts and network policy derive from the top-level `filesystem` and `network` sections, not from here. It is its own type rather than a shared one because a shared type would advertise its fields on every phase in the generated schema.",
+      "properties": {
+        "distribution": {
+          "description": "Distribution image (e.g. `alpine`).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "release": {
+          "description": "Distribution release (e.g. `3.23`).",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
     "Network": {
       "additionalProperties": false,
       "description": "Network access policy.",

sdk/node/README.md

@@ -240,7 +240,7 @@ capability names are reserved and must not be added directly to
 
 For long-lived sandboxes where you provision once, exec many times, and tear down at the end (e.g. agentic loops), use the state-aware lifecycle.
 
-> **Backend support:** the state-aware lifecycle is currently implemented for `isolation_session`, `windows_sandbox`, and `wslc` (all Windows-only; all still experimental, so every call must pass `{ experimental: true }`). The one-shot spawn APIs (`spawnSandbox` / `spawnSandboxFromConfig`) are the supported path for every other backend.
+> **Backend support:** the state-aware lifecycle is currently implemented for `isolation_session`, `windows_sandbox`, and `wslc` (all Windows-only; all still experimental, so every call must pass `{ experimental: true }`) and `lxc` (Linux-only; not experimental).  The one-shot spawn APIs (`spawnSandbox` / `spawnSandboxFromConfig`) are the supported path for every other backend.
 
 ```typescript
 import {
@@ -404,10 +404,10 @@ spawnSandboxFromConfig(config, options?, workingDirectory?, env?) → IPty | Chi
 spawnSandbox(script, policy, options?, workingDirectory?, containerName?, env?) → IPty
 spawnSandboxAsync(script, policy, ...) → Promise<{ stdout, stderr, exitCode }>
 
-// State-aware lifecycle (currently `isolation_session`, `windows_sandbox`, and `wslc` — all Windows-only)
+// State-aware lifecycle (`isolation_session`, `windows_sandbox`, and `wslc` — Windows-only, experimental; `lxc` — Linux-only)
 // `config` on provisionSandbox is required for backends whose provision config
-// has a required member (isolation_session: the network acknowledgment) and
-// optional otherwise (windows_sandbox, wslc).
+// has a required member (isolation_session: the network acknowledgment; lxc:
+// distribution and release) and optional otherwise (windows_sandbox, wslc).
 provisionSandbox(containment, config, options?)  → Promise<ProvisionResult>
 startSandbox(sandboxId, config?, options?)       → Promise<StartResult>
 execInSandbox(sandboxId, config, options?)       → IPty             // streaming