feat(driver-native): add containerd-backed native compute driver

Adds openshell-driver-native, an OCI/runc-based compute driver that
builds sandboxes from Linux namespaces and cgroups v2. A
system-provided containerd is used only for image pull, unpack, and
snapshot management: this driver, not containerd, drives the
configured low-level OCI runtime (runc/crun) directly, and containerd
never creates a Container or Task for these sandboxes.

Also extracts the VM driver's nftables ruleset generator into a
shared openshell-nft-ruleset crate, and wires
ComputeDriverKind::Native through openshell-core and every
openshell-server compute-driver selection path.

Hardening from review: sandbox names are validated against path
traversal, the runtime's --root is scoped under the driver's own
state directory instead of the shared global default, the sandbox
endpoint no longer defaults to an unreachable loopback address,
per-sandbox subnet allocation detects and avoids collisions instead
of a stateless hash, cleanup after a failed create no longer leaves a
mounted rootfs and bundle directory behind, and sandbox token files
are written with owner-only permissions.

Verified end to end against a real containerd 2.x + runc/crun install
(see tests/containerd_integration.rs, #[ignore]d in CI since CI has
no containerd). Known gaps (rootless mode, image-based supervisor
injection, full CDI GPU support, polling-based watch) are documented
in the driver README and docs/reference/sandbox-compute-drivers.mdx.

Related: #2255
Signed-off-by: Eric Curtin <eric.curtin@docker.com>

Author: ericcurtin

Cargo.lock

@@ -29,8 +29,8 @@ collect telemetry: `openshell-server` (gateway), `openshell-sandbox`
 (supervisor), and `openshell-driver-vm`. Every crate depends on
 `openshell-core` with `default-features = false`, so the binary crate's feature
 is the single switch that enables `openshell-core/telemetry` for its build
-graph. In-process drivers (`docker`, `kubernetes`, `podman`) inherit the
-gateway's setting through feature unification and carry no passthrough.
+graph. In-process drivers (`docker`, `kubernetes`, `podman`, `native`) inherit
+the gateway's setting through feature unification and carry no passthrough.
 
 Building a binary with `--no-default-features` compiles out telemetry entirely:
 no endpoint, no telemetry HTTP client, and no emission code. With telemetry

architecture/build.md

@@ -38,12 +38,14 @@ of re-querying drivers on each request.
 | Podman | Rootless or single-machine deployments. | Container plus nested sandbox namespace. | Uses the Podman REST API, OCI image volumes, and CDI GPU devices when available. |
 | Kubernetes | Cluster deployment through Helm. | Pod plus nested sandbox namespace. | Uses Kubernetes API objects, service accounts, secrets, PVC-backed workspace storage, and GPU resources. |
 | VM | Experimental microVM isolation. | Per-sandbox libkrun VM. | Managed endpoint-backed driver. The gateway spawns `openshell-driver-vm`, waits for its Unix socket, and then consumes it through the same remote `compute_driver.proto` path used by unmanaged endpoint drivers. The VM driver boots a cached bootstrap `rootfs.ext4`, prepares requested OCI images inside a bootstrap VM with `umoci`, attaches the prepared image disk read-only, and gives each sandbox a writable `overlay.ext4` for merged-root changes and runtime material. The driver persists each accepted launch request beside the overlay and restarts those VMs on driver startup without recreating the overlay. |
-| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a non-reserved custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. Reserved built-in names such as `vm`, `docker`, `podman`, and `kubernetes` cannot be used as unmanaged socket endpoints. The gateway connects to a UDS the operator already provisioned, runs `GetCapabilities`, logs the advertised `driver_name`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
+| Native | Early/opt-in kernel-primitive isolation against an existing system `containerd`. | Container built from Linux namespaces + cgroups v2. | In-process driver, like Docker/Podman/Kubernetes. The driver itself — not containerd — spawns the configured `runtime_binary` (`runc` by default, `crun`, or another OCI-runtime-spec-compatible binary) directly through its `create`/`start`/`state`/`delete` CLI contract; containerd is used only for image pull/unpack and snapshot management (protected from containerd's GC via a lease, since no containerd `Container`/`Task` is ever created) and never bundled. Sandboxes are tracked by scanning the driver's own state directory rather than querying containerd or the runtime for a global list. Per-sandbox network namespace + veth pair + nftables ruleset (shared `openshell-nft-ruleset` crate, also used by the VM driver). GPU support is kernel-device-node passthrough only. Rootless mode is implemented but not yet functional (defaults off) — see `crates/openshell-driver-native/README.md`. |
+| Extension | Out-of-tree drivers operated alongside the gateway. | Whatever boundary the driver implements. | Selected by a non-reserved custom `compute_drivers = ["<name>"]` entry with `[openshell.drivers.<name>].socket_path`, or at launch time by pairing `--drivers <name>` with `--compute-driver-socket=<path>`. Reserved built-in names such as `vm`, `docker`, `podman`, `kubernetes`, and `native` cannot be used as unmanaged socket endpoints. The gateway connects to a UDS the operator already provisioned, runs `GetCapabilities`, logs the advertised `driver_name`, and dispatches all sandbox lifecycle calls through `compute_driver.proto`. The driver process and socket lifecycle are operator-owned; the gateway does not spawn, supervise, or remove unmanaged extension drivers. The trust boundary is the socket's filesystem permissions: the operator must ensure only the gateway uid can read/write it. |
 
 Per-sandbox CPU and memory values currently enter the driver layer through
 template resource limits. Docker and Podman apply them as runtime limits.
 Kubernetes mirrors each limit into the matching request. VM accepts the fields
-but currently ignores them.
+but currently ignores them. Native applies them as cgroup v2 CPU quota/period
+and memory limits in the generated OCI spec.
 
 Docker and Podman also accept per-sandbox driver-config mounts for existing
 runtime-managed named volumes and tmpfs mounts. Podman additionally accepts
@@ -76,6 +78,7 @@ Runtime-specific implementation notes belong in the driver crate README:
 - `crates/openshell-driver-podman/README.md`
 - `crates/openshell-driver-kubernetes/README.md`
 - `crates/openshell-driver-vm/README.md`
+- `crates/openshell-driver-native/README.md`
 
 The combined VM topology runs `openshell-sandbox` as guest PID 1. libkrun
 executes the driver-owned guest bootstrap as PID 1, and the bootstrap preserves
@@ -91,6 +94,7 @@ The supervisor must be available inside each sandbox workload:
 | Podman | Read-only OCI image volume containing the supervisor binary. |
 | Kubernetes | Supervisor image side-loaded into the sandbox pod by image volume or init container. |
 | VM | Embedded in the guest rootfs bundle. |
+| Native | Bind-mounted from a host path (`supervisor_binary_path`), not sourced from an image like the other in-tree drivers — see the driver README's Known Gaps. |
 | Extension | Defined by the out-of-tree driver. |
 
 Driver-controlled environment variables must override sandbox image or template

architecture/compute-runtimes.md

@@ -87,6 +87,7 @@ pub enum ComputeDriverKind {
     Vm,
     Docker,
     Podman,
+    Native,
 }
 
 impl ComputeDriverKind {
@@ -97,6 +98,7 @@ impl ComputeDriverKind {
             Self::Vm => "vm",
             Self::Docker => "docker",
             Self::Podman => "podman",
+            Self::Native => "native",
         }
     }
 }
@@ -137,8 +139,9 @@ impl FromStr for ComputeDriverKind {
             "vm" => Ok(Self::Vm),
             "docker" => Ok(Self::Docker),
             "podman" => Ok(Self::Podman),
+            "native" => Ok(Self::Native),
             other => Err(format!(
-                "unsupported compute driver '{other}'. expected one of: kubernetes, vm, docker, podman"
+                "unsupported compute driver '{other}'. expected one of: kubernetes, vm, docker, podman, native"
             )),
         }
     }
@@ -1001,6 +1004,10 @@ mod tests {
             "docker".parse::<ComputeDriverKind>().unwrap(),
             ComputeDriverKind::Docker
         );
+        assert_eq!(
+            "native".parse::<ComputeDriverKind>().unwrap(),
+            ComputeDriverKind::Native
+        );
     }
 
     #[test]

crates/openshell-core/src/config.rs

@@ -161,6 +161,7 @@ pub enum TelemetryComputeDriver {
     Kubernetes,
     Podman,
     Vm,
+    Native,
     Unknown,
 }
 
@@ -172,6 +173,7 @@ impl TelemetryComputeDriver {
             Self::Kubernetes => "kubernetes",
             Self::Podman => "podman",
             Self::Vm => "vm",
+            Self::Native => "native",
             Self::Unknown => "unknown",
         }
     }
@@ -183,6 +185,7 @@ impl TelemetryComputeDriver {
             "k8s" | "kubernetes" => Self::Kubernetes,
             "podman" => Self::Podman,
             "vm" => Self::Vm,
+            "native" => Self::Native,
             _ => Self::Unknown,
         }
     }
@@ -194,6 +197,7 @@ impl TelemetryComputeDriver {
             Some(crate::ComputeDriverKind::Kubernetes) => Self::Kubernetes,
             Some(crate::ComputeDriverKind::Podman) => Self::Podman,
             Some(crate::ComputeDriverKind::Vm) => Self::Vm,
+            Some(crate::ComputeDriverKind::Native) => Self::Native,
             None => Self::Unknown,
         }
     }

crates/openshell-core/src/telemetry.rs

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "openshell-driver-native"
+description = "Linux-native compute driver for OpenShell, backed by a system-provided containerd"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+name = "openshell_driver_native"
+path = "src/lib.rs"
+
+[[bin]]
+name = "openshell-driver-native"
+path = "src/main.rs"
+
+[dependencies]
+openshell-core = { path = "../openshell-core", default-features = false }
+openshell-nft-ruleset = { path = "../openshell-nft-ruleset" }
+openshell-policy = { path = "../openshell-policy" }
+
+# containerd's own generated gRPC client. This is the "system-provided
+# containerd" integration point, used only for image pull/unpack and
+# snapshot management (see src/image.rs) -- never bundled, installed, or
+# managed by this driver. The driver itself, not containerd, spawns the
+# configured low-level OCI runtime (runc/crun/etc.) directly (see
+# src/runtime.rs); containerd's container/task services and shim are
+# never used.
+containerd-client = "0.9"
+# OCI runtime-spec and image-spec types (namespaces, cgroups v2 resources,
+# seccomp, image manifest/config parsing for chain-ID computation).
+oci-spec = { version = "0.10", default-features = false, features = [
+  "runtime",
+  "image",
+] }
+
+tokio = { workspace = true }
+tokio-stream = { workspace = true }
+tonic = { workspace = true, features = ["transport"] }
+prost = { workspace = true }
+prost-types = { workspace = true }
+futures = { workspace = true }
+clap = { workspace = true }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true }
+miette = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+nix = { workspace = true }
+rand = { workspace = true }
+thiserror = { workspace = true }
+sha2 = "0.10"
+
+[dev-dependencies]
+tempfile = "3"
+
+[lints]
+workspace = true