Container Dev Mode: host CLI, embedded registry, and VM push path

Cargo.toml

@@ -31,10 +31,15 @@ tokio = { version = "1.0", features = [
     "rt-multi-thread",
     "process",
     "io-util",
+    "fs",
     "signal",
     "time",
     "sync",
 ] }
+# `io` only, for ReaderStream: the registry streams stored blobs off disk instead
+# of sizing an allocation by the blob. Already in the tree transitively (axum,
+# tokio-tungstenite), so this adds an explicit edge rather than a new dependency.
+tokio-util = { version = "0.7", features = ["io"] }
 thiserror = "2.0"
 directories = "6.0"
 reqwest = { version = "0.13", default-features = false, features = [
@@ -70,7 +75,25 @@ tough = { version = "0.22", default-features = false }
 semver = "1"
 crossterm = "0.29"
 num_cpus = "1.16"
+# Container Dev Mode embedded registry server surface. Pure-Rust HTTP/TLS/WS
+# stack pinned to the aws-lc-rs rustls provider already linked via reqwest, so
+# no new C toolchain requirement is introduced. rcgen and tokio-tungstenite
+# both default to aws_lc_rs; do not enable a `ring` feature here or a second
+# crypto provider would be linked.
+axum = "0.8"
+rustls = "0.23"
+tokio-rustls = "0.26"
+rcgen = { version = "0.13", default-features = false, features = [
+    "crypto",
+    "pem",
+    "aws_lc_rs",
+] }
+tokio-tungstenite = { version = "0.26", features = ["rustls-tls-native-roots"] }
 
 [dev-dependencies]
+# `oneshot` drives the write router directly, so a body stream that ERRORS can be
+# injected deterministically - a truncated real HTTP body just makes the server
+# wait for bytes that never arrive.
+tower = { version = "0.5", features = ["util"] }
 tokio-test = "0.4"
 serial_test = "3.0"

docs/container-dev/lab/README.md

@@ -0,0 +1,67 @@
+# Container Dev Mode - local VM write-path lab
+
+A from-scratch harness to exercise Container Dev Mode's authenticated VM write
+path (task 7.1) on Linux, without hardware. It stands up a disposable Debian 12
+"engine VM" under QEMU user-mode networking so the guest reaches the host at
+`10.0.2.2` exactly like the macOS `avocado-vm`, then runs the end-to-end verify.
+
+This is the setup the 2026-07-23 field note ("Container Dev Mode VM push") was
+written from; it validated the path 8/8 and caught two real bugs (a plain-HTTP
+write listener where the guest required HTTPS, and a 2 MiB body limit that
+413'd real layers).
+
+## What's here
+
+- `setup-lab.sh` - idempotent provisioner: ssh keypair, cloud-init seed
+  (`docker.io` + root login), a copy-on-write overlay off the Debian base, a
+  QEMU SLIRP boot with an ssh hostfwd, a forward of the guest dockerd to the
+  socket `is_vm_routing_active()` resolves, and an `env.sh` for the verify step.
+- `avocado.yaml` - the minimal `container_dev` runtime config the lab uses.
+- `../verify-vm-write-path.sh` - the actual end-to-end assertion (built image ->
+  authenticated push over `10.0.2.2` HTTPS -> single-layer sync). Sourced env
+  comes from the generated `env.sh`.
+
+Generated state (the qcow2 overlay, ssh key, cloud-init seed, `env.sh`) is
+written to a work dir OUTSIDE this repo (`$AVOCADO_CDM_LAB_WORK`, default
+`~/.cache/avocado-cdm-lab`) so a ~900 MB overlay never lands in git.
+
+## Prerequisites
+
+Host packages: `qemu-system-x86_64`, `qemu-img`, `cloud-image-utils`
+(`cloud-localds`), `ssh`/`ssh-keygen`, and the `docker` client.
+
+## Run it (from scratch)
+
+```bash
+# 1. one-time: download a Debian 12 generic-cloud base image
+WORK="${AVOCADO_CDM_LAB_WORK:-$HOME/.cache/avocado-cdm-lab}"
+mkdir -p "$WORK"
+curl -L -o "$WORK/debian12.qcow2" \
+  https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2
+
+# 2. build the avocado CLI (the lab points AVOCADO_BIN at target/debug/avocado)
+cargo build --bin avocado
+
+# 3. stand up the engine VM (interactive: it runs ssh-keygen + touches ~/.ssh)
+bash docs/container-dev/lab/setup-lab.sh
+
+# 4. run the end-to-end verify
+source "$WORK/env.sh"
+docs/container-dev/verify-vm-write-path.sh
+```
+
+Optional: set `BBAPPEND` to the meta-avocado
+`meta-avocado-qemu/recipes-core/base-files/base-files_%.bbappend` path so the
+verify script also checks the guest trust-store-dir overlay; leave it empty to
+skip that check.
+
+## Tear down
+
+```bash
+WORK="${AVOCADO_CDM_LAB_WORK:-$HOME/.cache/avocado-cdm-lab}"
+kill "$(cat "$WORK/qemu.pid")" 2>/dev/null || true
+pkill -f "$HOME/.avocado/vm/docker.sock:" 2>/dev/null || true
+```
+
+Deleting `$WORK/engine.qcow2` gives a clean VM on the next run; the base image
+and ssh key are reused.

docs/container-dev/lab/avocado.yaml

@@ -0,0 +1,24 @@
+# HOST-side session config for the Container Dev Mode lab.
+#
+# There are deliberately two avocado.yaml files in this lab and they do different
+# jobs. This one is read by the host CLI (`container dev up` runs from this
+# directory) and only has to carry the `container_dev` block. The one setup-lab.sh
+# renders into $AVOCADO_CDM_LAB_WORK/hitl is the RUNTIME BUILD config - it composes
+# the Avocado OS image with avocado-ext-docker and avocado-ext-container-agent-dev.
+# That one is generated rather than tracked because the agent extension is not in
+# the published feed and has to be sourced by absolute path.
+#
+# A runtime carrying a `container_dev` block is all that enables the feature
+# (see src/utils/container_dev/config.rs). The watched image ref must match the
+# image the verify script builds on the VM engine (TEST_IMAGE, default
+# my-app:dev). `registry.port` is the bulk *read* listener; the authenticated
+# *write* listener uses AVOCADO_CONTAINER_DEV_WRITE_PORT (default 5601).
+runtimes:
+  dev:
+    target: qemux86-64
+    container_dev:
+      images:
+        - ref: my-app:dev
+          service: app
+      registry:
+        port: 5599