feat(vm): add OCI container container support to vm driver

[drew]

Summary

Add host-side OCI container execution to the VM compute driver so sandboxes can boot from a user-specified template.image without introducing a Docker runtime into the guest. The driver pulls and flattens the image into a cached read-only squashfs; the guest mounts that RO base plus a per-sandbox writable disk as an overlay, pivot_roots into the merged view, and execs an unmodified openshell-sandbox with the OCI argv/env/workdir.

Related Issue

N/A — tracked via the internal architecture plan for VM-driver OCI container execution.

Changes

Host-side OCI pipeline (crates/openshell-driver-vm/src/oci/)

• client.rs — anonymous oci-client pulls pinned to linux/amd64/linux/arm64; normalizes the image config.
• flatten.rs — applies OCI layer tars in order with whiteout (.wh.*, .wh..wh..opq) handling; rejects absolute and parent-traversal paths.
• compat.rs — injects sandbox:10001 into /etc/passwd and /etc/group, ensures /sandbox and /tmp, stubs /etc/hosts and /etc/resolv.conf if missing. Idempotent.
• fs_image.rs — shells out to mksquashfs with an explicit binary path (no $PATH reliance), zstd by default.
• cache.rs — content-addressed layout blobs/ + fs/<hex>.<plat>.squashfs + meta/<hex>.<plat>.json + tmp/ with atomic writes and idempotent install/lookup.
• metadata.rs — LaunchMetadata::build enforces OCI precedence (argv = Entrypoint + Cmd; workdir fallback /sandbox; env merge order OCI < template < spec). to_guest_env_vars() packs argv/env/workdir into OPENSHELL_OCI_* for delivery via libkrun set_exec.
• pipeline.rs — orchestrates pull → flatten → compat → squashfs → install; short-circuits on cache hit after digest resolution.

VM boot and guest init

• runtime.rs/main.rs — VmLaunchConfig now supports attaching two disks (oci-base RO + sandbox-state RW) via krun_add_disk3; optional import vsock is kept but unused by the overlay path.
• state_disk.rs — per-sandbox raw sparse state disk (16 GiB default), lifecycle-bound to the sandbox state dir.
• scripts/openshell-vm-sandbox-init.sh — new oci_launch_supervisor path: resolves disks by libkrun-assigned serial via /sys/block/vd*/serial, mounts RO base + ext4 state, creates the overlay, bind-mounts the workspace over /sandbox, stages TLS CA and the supervisor binary into the upper layer, bind-mounts /proc,/sys,/dev, pivot_roots, translates OCI env → OPENSHELL_CONTAINER_ENV_<i>, sets OPENSHELL_CONTAINER_MODE=1, and execs openshell-sandbox --workdir <wd> -- <argv>.

Supervisor clean-env mode (crates/openshell-sandbox/src/container_env.rs)

• Gated on OPENSHELL_CONTAINER_MODE=1. When active, the child process starts from env_clear() and receives only a documented allowlist (HOME/PATH/TERM defaults, OPENSHELL_CONTAINER_ENV_<i>, and OPENSHELL_SANDBOX=1 applied last so images cannot override the marker). Provider/proxy/TLS env continue to layer in via the existing spawn path.

Gateway wiring (crates/openshell-server/src/compute/vm.rs, cli.rs)

• Extracted argv construction into a testable build_driver_argv helper.
• Gateway now passes --default-image <sandbox_image> on every VM-driver spawn so GetCapabilities.default_image cannot silently diverge from gateway config.
• New VmComputeConfig::mksquashfs_bin + --vm-mksquashfs-bin / OPENSHELL_VM_MKSQUASHFS flag plumbs the squashfs builder path to the driver.

Driver behavior

• validate_vm_sandbox rejects malformed template.image refs and unsupported template fields.
• resolve_oci_launch returns FailedPrecondition when the host arch isn't linux/{amd64,arm64} or mksquashfs_bin is unset.
• build_guest_environment skips the legacy OPENSHELL_SANDBOX_COMMAND=tail -f /dev/null fallback for OCI sandboxes so argv boundaries can't be corrupted by a fall-through code path.

Docs

• New architecture/vm-driver.md covers the OCI execution model, module responsibilities, storage layout, driver configuration, and v1 scope.

Testing

• cargo test -p openshell-driver-vm --lib — 80/80 pass (flatten, compat, fs_image, cache, metadata, pipeline, state_disk, driver, including 3 new resolve_oci_launch tests and new OCI-mode guest env tests).
• cargo test -p openshell-server --lib compute::vm — 8/8 pass (6 new argv-wiring tests + 2 existing TLS tests).
• cargo fmt --check clean on touched crates.
• cargo clippy on touched crates — no errors (pre-existing warnings in unrelated openshell-ocsf crate are out of scope).
• mise run license:check — all 398 files have SPDX headers.
• bash -n on the updated guest init script.
• Integration test oci_pipeline_integration::full_pipeline_without_network_produces_cached_image (gated on mksquashfs being in \$PATH, run with --ignored) verifies flatten → compat → squashfs → cache install → round-trip.

E2E against a live cluster with a public image (alpine, busybox) was not run as part of this PR; the plan's end-to-end acceptance is scheduled for a follow-up once gateway+driver integration lands on main.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (architecture/vm-driver.md)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.