1 files changed, 159 insertions, 0 deletions

diff --git a/recipes-core/vxn/README.md b/recipes-core/vxn/README.md
new file mode 100644
index 00000000..35802e31
--- /dev/null
+++ b/recipes-core/vxn/README.md
@@ -0,0 +1,159 @@
+# vxn — Docker CLI for Xen DomU Containers
+
+vxn runs OCI containers as Xen DomU guests. The VM IS the container — no
+Docker/Podman daemon runs inside the guest. The guest boots a minimal Linux,
+mounts the container's filesystem, and directly executes the entrypoint.
+
+## Packages
+
+| Package | Contents | Usage |
+|---------|----------|-------|
+| `vxn` | CLI, OCI runtime, blobs, containerd config | Base package (required) |
+| `vxn-vdkr` | `vdkr` — Docker-like CLI frontend | `IMAGE_INSTALL:append = " vxn-vdkr"` |
+| `vxn-vpdmn` | `vpdmn` — Podman-like CLI frontend | `IMAGE_INSTALL:append = " vxn-vpdmn"` |
+| `vxn-docker-config` | `/etc/docker/daemon.json` (vxn as default runtime) | `IMAGE_INSTALL:append = " vxn-docker-config"` |
+| `vxn-podman-config` | `/etc/containers/containers.conf.d/50-vxn-runtime.conf` | `IMAGE_INSTALL:append = " vxn-podman-config"` |
+
+## Execution Paths
+
+### 1. containerd (vctr/ctr) — recommended
+
+No additional packages needed beyond `vxn`. containerd is configured
+automatically via `/etc/containerd/config.toml`.
+
+```bash
+ctr image pull docker.io/library/alpine:latest
+vctr run --rm docker.io/library/alpine:latest test1 /bin/echo hello
+ctr run -t --rm --runtime io.containerd.vxn.v2 docker.io/library/alpine:latest tty1 /bin/sh
+```
+
+### 2. vdkr/vpdmn (Docker/Podman-like CLI, no daemon)
+
+Install `vxn-vdkr` or `vxn-vpdmn`. These are standalone frontends that
+auto-detect Xen (via `xl`) and manage containers without any daemon process.
+They handle OCI image pull/unpack on the host via skopeo.
+
+```bash
+vdkr run --rm alpine echo hello        # Docker-like
+vpdmn run --rm alpine echo hello       # Podman-like
+```
+
+Persistent DomU (memres) for faster subsequent runs:
+```bash
+vdkr vmemres start                     # Boot persistent DomU (~10s)
+vdkr run --rm alpine echo hello        # Hot-plug container (~1s)
+vdkr vmemres stop                      # Shutdown DomU
+```
+
+### 3. Native Docker with vxn runtime
+
+Install `vxn-docker-config` to register vxn-oci-runtime as Docker's default
+OCI runtime. Docker manages images (pull/tag/rmi) natively.
+
+```bash
+docker run --rm --network=none alpine echo hello
+docker run --rm --network=host alpine echo hello
+```
+
+**IMPORTANT: Networking** — Docker's default bridge networking is incompatible
+with VM-based runtimes. Docker tries to create veth pairs and move them into
+a Linux network namespace, but vxn containers are Xen DomUs with their own
+kernel network stack. You MUST use `--network=none` or `--network=host`.
+
+This is the same limitation as kata-containers. The long-term fix is a TAP
+bridge that connects Docker's network namespace to the DomU's vif (see TODO).
+
+For selective use (keep runc as default, use vxn per-run):
+```bash
+docker run --rm --runtime=vxn --network=none alpine echo hello
+```
+
+### 4. Native Podman with vxn runtime
+
+Install `vxn-podman-config` to register vxn-oci-runtime as Podman's default
+OCI runtime. Same networking constraints as Docker.
+
+```bash
+podman run --rm --network=none alpine echo hello
+```
+
+## Build Instructions
+
+```bash
+# Prerequisites in local.conf:
+DISTRO_FEATURES:append = " xen virtualization vcontainer"
+BBMULTICONFIG = "vruntime-aarch64 vruntime-x86-64"
+
+# Build (mcdepends auto-builds vruntime blobs)
+bitbake vxn
+
+# Dom0 image with containerd + Docker-like CLI
+IMAGE_INSTALL:append = " vxn vxn-vdkr"
+
+# Dom0 image with native Docker integration
+IMAGE_INSTALL:append = " vxn vxn-docker-config docker"
+
+bitbake xen-image-minimal
+```
+
+## Architecture
+
+```
+Docker/Podman/containerd → vxn-oci-runtime → xl create/unpause/destroy → Xen DomU
+                                                                            ↓
+                                                                      vxn-init.sh
+                                                                        mount rootfs
+                                                                        chroot + exec
+```
+
+The OCI runtime (`/usr/bin/vxn-oci-runtime`) implements the standard
+create/start/state/kill/delete lifecycle by mapping to xl commands:
+
+| OCI Command | xl Equivalent |
+|-------------|---------------|
+| create | xl create -p (paused) |
+| start | xl unpause |
+| state | xl list + monitor PID check |
+| kill SIGTERM | xl shutdown (10s grace) + xl destroy |
+| kill SIGKILL | xl destroy |
+| delete | xl destroy + cleanup state |
+
+## Networking Constraints (Native Docker/Podman)
+
+Docker and Podman's default bridge networking creates Linux veth pairs and
+moves one end into a container network namespace. This is fundamentally
+incompatible with VM-based runtimes where the "container" is a VM with its
+own kernel networking.
+
+**Current workarounds:**
+- `--network=none` — DomU uses its own xenbr0 networking
+- `--network=host` — Tells Docker/Podman to skip namespace setup
+
+**Future fix (TODO):**
+TAP bridge integration — read Docker's network namespace config from
+config.json, create a TAP device bridged to the DomU's vif. This is the
+approach kata-containers uses to provide Docker-compatible networking with
+VM isolation.
+
+**Not affected:**
+- `vctr`/`ctr` (containerd) — CNI is separate and opt-in
+- `vdkr`/`vpdmn` — Handle networking independently via xenbr0
+
+## Debugging
+
+```bash
+# OCI runtime log (all invocations)
+cat /var/log/vxn-oci-runtime.log
+
+# Per-container console capture (persists after container exit)
+ls /var/log/vxn-oci-runtime/containers/
+
+# Xen domain status
+xl list
+
+# Watch domain console
+xl console <domname>
+
+# Kill stuck domain
+xl destroy <domname>
+```