8 files changed, 470 insertions, 101 deletions

diff --git a/recipes-containers/container-registry/container-oci-registry-config.bb b/recipes-containers/container-registry/container-oci-registry-config.bb
index 294defc3..5161f0a3 100644
--- a/recipes-containers/container-registry/container-oci-registry-config.bb
+++ b/recipes-containers/container-registry/container-oci-registry-config.bb
@@ -64,12 +64,19 @@ CONTAINER_REGISTRY_SEARCH_FIRST ?= "1"
 # NOT stored in bitbake - should point to external file
 CONTAINER_REGISTRY_AUTHFILE ?= ""
 
+# OCI runtime configuration for Podman
+# Runtime name (e.g. "vxn") — creates a containers.conf.d drop-in
+PODMAN_OCI_RUNTIME ?= ""
+# Path to OCI runtime binary (e.g. "/usr/bin/vxn-oci-runtime")
+PODMAN_OCI_RUNTIME_PATH ?= ""
+
 # Skip recipe entirely if not configured
 # User must explicitly set CONTAINER_REGISTRY_URL to enable
 python() {
     registry = d.getVar('CONTAINER_REGISTRY_URL')
-    if not registry:
-        raise bb.parse.SkipRecipe("CONTAINER_REGISTRY_URL not set - recipe is opt-in only")
+    oci_runtime = (d.getVar('PODMAN_OCI_RUNTIME') or "").strip()
+    if not registry and not oci_runtime:
+        raise bb.parse.SkipRecipe("No registry or OCI runtime configured - recipe is opt-in only")
 
     # Check for conflicting settings
     secure = d.getVar('CONTAINER_REGISTRY_SECURE') == '1'
@@ -94,63 +101,85 @@ python do_install() {
     search_first = d.getVar('CONTAINER_REGISTRY_SEARCH_FIRST') == "1"
     ca_cert = d.getVar('CONTAINER_REGISTRY_CA_CERT')
     authfile = d.getVar('CONTAINER_REGISTRY_AUTHFILE') or ''
-
-    # Extract registry host (strip any path)
-    registry_host = registry.split('/')[0] if '/' in registry else registry
+    oci_runtime = (d.getVar('PODMAN_OCI_RUNTIME') or "").strip()
+    oci_runtime_path = (d.getVar('PODMAN_OCI_RUNTIME_PATH') or "").strip()
 
     dest = d.getVar('D')
-    confdir = os.path.join(dest, d.getVar('sysconfdir').lstrip('/'),
-                           'containers', 'registries.conf.d')
-    os.makedirs(confdir, exist_ok=True)
 
-    # Install CA cert in secure mode
-    if secure:
-        if os.path.exists(ca_cert):
-            cert_dir = os.path.join(dest, 'etc/containers/certs.d', registry_host)
-            os.makedirs(cert_dir, exist_ok=True)
-            shutil.copy(ca_cert, os.path.join(cert_dir, 'ca.crt'))
-            bb.note(f"Installed CA certificate for registry: {registry_host}")
-        else:
-            bb.warn(f"Secure mode enabled but CA certificate not found at {ca_cert}")
-            bb.warn("Run 'container-registry.sh start' to generate PKI, then rebuild this package")
-
-    # In secure mode, insecure should be false
-    if secure:
-        insecure = False
-
-    # Generate drop-in config
-    # Filename starts with 50- so it's processed after base config but
-    # can be overridden by higher-numbered files
-    config_path = os.path.join(confdir, '50-custom-registry.conf')
-
-    with open(config_path, 'w') as f:
-        f.write(f"# Custom container registry: {registry}\n")
-        f.write(f"# Generated by container-oci-registry-config recipe\n")
-        f.write(f"# This is ADDITIVE - base registries.conf is unchanged\n")
-        f.write(f"# Public registries (docker.io, quay.io) remain accessible\n")
-        f.write(f"#\n")
+    # --- Registry configuration ---
+    if registry:
+        # Extract registry host (strip any path)
+        registry_host = registry.split('/')[0] if '/' in registry else registry
+
+        confdir = os.path.join(dest, d.getVar('sysconfdir').lstrip('/'),
+                               'containers', 'registries.conf.d')
+        os.makedirs(confdir, exist_ok=True)
+
+        # Install CA cert in secure mode
         if secure:
-            f.write(f"# Mode: secure (TLS with CA certificate verification)\n")
-            f.write(f"# CA cert: /etc/containers/certs.d/{registry_host}/ca.crt\n")
-        else:
-            f.write(f"# Mode: insecure (HTTP or untrusted TLS)\n")
-        f.write(f"#\n")
-        f.write(f"# To remove: uninstall container-oci-registry-config package\n")
-        f.write(f"# or delete this file\n\n")
-
-        if search_first:
-            # Add to unqualified-search-registries
-            # This means short names like "myapp:latest" will search here first
-            f.write(f"# Search this registry for unqualified image names\n")
-            f.write(f'unqualified-search-registries = ["{registry}"]\n\n')
-
-        # Always create registry entry to set insecure flag explicitly
-        f.write(f'[[registry]]\n')
-        f.write(f'location = "{registry_host}"\n')
-        if insecure:
-            f.write(f'insecure = true\n')
-        else:
-            f.write(f'insecure = false\n')
+            if os.path.exists(ca_cert):
+                cert_dir = os.path.join(dest, 'etc/containers/certs.d', registry_host)
+                os.makedirs(cert_dir, exist_ok=True)
+                shutil.copy(ca_cert, os.path.join(cert_dir, 'ca.crt'))
+                bb.note("Installed CA certificate for registry: %s" % registry_host)
+            else:
+                bb.warn("Secure mode enabled but CA certificate not found at %s" % ca_cert)
+                bb.warn("Run 'container-registry.sh start' to generate PKI, then rebuild this package")
+
+        # In secure mode, insecure should be false
+        if secure:
+            insecure = False
+
+        # Generate drop-in config
+        config_path = os.path.join(confdir, '50-custom-registry.conf')
+
+        with open(config_path, 'w') as f:
+            f.write("# Custom container registry: %s\n" % registry)
+            f.write("# Generated by container-oci-registry-config recipe\n")
+            f.write("# This is ADDITIVE - base registries.conf is unchanged\n")
+            f.write("# Public registries (docker.io, quay.io) remain accessible\n")
+            f.write("#\n")
+            if secure:
+                f.write("# Mode: secure (TLS with CA certificate verification)\n")
+                f.write("# CA cert: /etc/containers/certs.d/%s/ca.crt\n" % registry_host)
+            else:
+                f.write("# Mode: insecure (HTTP or untrusted TLS)\n")
+            f.write("#\n")
+            f.write("# To remove: uninstall container-oci-registry-config package\n")
+            f.write("# or delete this file\n\n")
+
+            if search_first:
+                f.write("# Search this registry for unqualified image names\n")
+                f.write('unqualified-search-registries = ["%s"]\n\n' % registry)
+
+            f.write('[[registry]]\n')
+            f.write('location = "%s"\n' % registry_host)
+            if insecure:
+                f.write('insecure = true\n')
+            else:
+                f.write('insecure = false\n')
+
+        mode = "secure" if secure else ("insecure" if insecure else "default")
+        bb.note("Created registry config for %s (mode=%s)" % (registry, mode))
+
+    # --- OCI runtime configuration ---
+    if oci_runtime:
+        dropin_dir = os.path.join(dest, d.getVar('sysconfdir').lstrip('/'),
+                                  'containers', 'containers.conf.d')
+        os.makedirs(dropin_dir, exist_ok=True)
+
+        runtime_path = oci_runtime_path if oci_runtime_path else "/usr/bin/%s" % oci_runtime
+        dropin_path = os.path.join(dropin_dir, '50-oci-runtime.conf')
+
+        with open(dropin_path, 'w') as f:
+            f.write("# OCI runtime configuration\n")
+            f.write("# Generated by container-oci-registry-config recipe\n\n")
+            f.write("[engine]\n")
+            f.write('runtime = "%s"\n\n' % oci_runtime)
+            f.write("[engine.runtimes]\n")
+            f.write('%s = ["%s"]\n' % (oci_runtime, runtime_path))
+
+        bb.note("Created OCI runtime drop-in for %s (%s)" % (oci_runtime, runtime_path))
 
     # Install authfile if provided (for baked credentials)
     if authfile and os.path.exists(authfile):
@@ -159,14 +188,12 @@ python do_install() {
         auth_json = os.path.join(containers_dir, 'auth.json')
         shutil.copy(authfile, auth_json)
         os.chmod(auth_json, 0o600)
-        bb.note(f"Installed OCI auth config from {authfile}")
-
-    mode = "secure" if secure else ("insecure" if insecure else "default")
-    bb.note(f"Created registry config for {registry} (mode={mode})")
+        bb.note("Installed OCI auth config from %s" % authfile)
 }
 
 FILES:${PN} = " \
     ${sysconfdir}/containers/registries.conf.d \
+    ${sysconfdir}/containers/containers.conf.d \
     ${sysconfdir}/containers/certs.d/*/ca.crt \
     ${sysconfdir}/containers/auth.json \
 "
diff --git a/recipes-containers/container-registry/docker-registry-config.bb b/recipes-containers/container-registry/docker-registry-config.bb
index 0e8d66ad..e558cccb 100644
--- a/recipes-containers/container-registry/docker-registry-config.bb
+++ b/recipes-containers/container-registry/docker-registry-config.bb
@@ -60,6 +60,13 @@ DOCKER_REGISTRY_INSECURE ?= ""
 # NOT stored in bitbake - should point to external file
 CONTAINER_REGISTRY_AUTHFILE ?= ""
 
+# OCI runtime configuration for Docker daemon
+# JSON object mapping runtime names to paths, e.g.:
+#   DOCKER_OCI_RUNTIMES = '{"vxn": {"path": "/usr/bin/vxn-oci-runtime"}}'
+DOCKER_OCI_RUNTIMES ?= ""
+# Default OCI runtime name (must be a key in DOCKER_OCI_RUNTIMES or "runc")
+DOCKER_DEFAULT_RUNTIME ?= ""
+
 def get_insecure_registries(d):
     """Get insecure registries from either Docker-specific or generic config"""
     # Prefer explicit DOCKER_REGISTRY_INSECURE if set
@@ -87,8 +94,10 @@ python() {
         bb.fatal("CONTAINER_REGISTRY_SECURE='1' conflicts with insecure registry settings. "
                  "Use secure mode (TLS+auth) OR insecure mode (HTTP), not both.")
 
-    if not secure and not registries:
-        raise bb.parse.SkipRecipe("No registry configured - recipe is opt-in only")
+    oci_runtimes = (d.getVar('DOCKER_OCI_RUNTIMES') or "").strip()
+
+    if not secure and not registries and not oci_runtimes:
+        raise bb.parse.SkipRecipe("No registry or OCI runtime configured - recipe is opt-in only")
 
     # In secure mode, depend on PKI generation
     if secure:
@@ -137,6 +146,17 @@ python do_install() {
             config["insecure-registries"] = registries
             bb.note(f"Created Docker config with insecure registries: {registries}")
 
+    # OCI runtime configuration
+    oci_runtimes = (d.getVar('DOCKER_OCI_RUNTIMES') or "").strip()
+    default_runtime = (d.getVar('DOCKER_DEFAULT_RUNTIME') or "").strip()
+
+    if oci_runtimes:
+        config["runtimes"] = json.loads(oci_runtimes)
+        bb.note("Added OCI runtimes to Docker config: %s" % oci_runtimes)
+    if default_runtime:
+        config["default-runtime"] = default_runtime
+        bb.note("Set default Docker runtime: %s" % default_runtime)
+
     # Install authfile if provided (for baked credentials)
     if authfile and os.path.exists(authfile):
         docker_dir = os.path.join(dest, 'root/.docker')
diff --git a/recipes-containers/vcontainer/files/vdkr.sh b/recipes-containers/vcontainer/files/vdkr.sh
index 818c831e..29f08877 100755
--- a/recipes-containers/vcontainer/files/vdkr.sh
+++ b/recipes-containers/vcontainer/files/vdkr.sh
@@ -21,5 +21,27 @@ VCONTAINER_STATE_FILE="docker-state.img"
 VCONTAINER_OTHER_PREFIX="VPDMN"
 VCONTAINER_VERSION="3.4.0"
 
-# Source common implementation
-source "$(dirname "${BASH_SOURCE[0]}")/vcontainer-common.sh" "$@"
+# Auto-detect Xen if not explicitly set
+if [ -z "${VCONTAINER_HYPERVISOR:-}" ]; then
+    if command -v xl >/dev/null 2>&1; then
+        export VCONTAINER_HYPERVISOR="xen"
+    fi
+fi
+
+# Fall back to vxn blob dir on Dom0
+if [ -z "${VDKR_BLOB_DIR:-}" ] && [ -d "/usr/share/vxn" ]; then
+    export VDKR_BLOB_DIR="/usr/share/vxn"
+fi
+
+# Two-phase lib lookup: script dir (dev), then /usr/lib/vxn (target)
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+if [ -f "${SCRIPT_DIR}/vcontainer-common.sh" ]; then
+    export VCONTAINER_LIBDIR="${SCRIPT_DIR}"
+    source "${SCRIPT_DIR}/vcontainer-common.sh" "$@"
+elif [ -f "/usr/lib/vxn/vcontainer-common.sh" ]; then
+    export VCONTAINER_LIBDIR="/usr/lib/vxn"
+    source "/usr/lib/vxn/vcontainer-common.sh" "$@"
+else
+    echo "Error: vcontainer-common.sh not found" >&2
+    exit 1
+fi
diff --git a/recipes-containers/vcontainer/files/vpdmn.sh b/recipes-containers/vcontainer/files/vpdmn.sh
index 30775d35..6f0f56d8 100755
--- a/recipes-containers/vcontainer/files/vpdmn.sh
+++ b/recipes-containers/vcontainer/files/vpdmn.sh
@@ -21,5 +21,27 @@ VCONTAINER_STATE_FILE="podman-state.img"
 VCONTAINER_OTHER_PREFIX="VDKR"
 VCONTAINER_VERSION="1.2.0"
 
-# Source common implementation
-source "$(dirname "${BASH_SOURCE[0]}")/vcontainer-common.sh" "$@"
+# Auto-detect Xen if not explicitly set
+if [ -z "${VCONTAINER_HYPERVISOR:-}" ]; then
+    if command -v xl >/dev/null 2>&1; then
+        export VCONTAINER_HYPERVISOR="xen"
+    fi
+fi
+
+# Fall back to vxn blob dir on Dom0
+if [ -z "${VPDMN_BLOB_DIR:-}" ] && [ -d "/usr/share/vxn" ]; then
+    export VPDMN_BLOB_DIR="/usr/share/vxn"
+fi
+
+# Two-phase lib lookup: script dir (dev), then /usr/lib/vxn (target)
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+if [ -f "${SCRIPT_DIR}/vcontainer-common.sh" ]; then
+    export VCONTAINER_LIBDIR="${SCRIPT_DIR}"
+    source "${SCRIPT_DIR}/vcontainer-common.sh" "$@"
+elif [ -f "/usr/lib/vxn/vcontainer-common.sh" ]; then
+    export VCONTAINER_LIBDIR="/usr/lib/vxn"
+    source "/usr/lib/vxn/vcontainer-common.sh" "$@"
+else
+    echo "Error: vcontainer-common.sh not found" >&2
+    exit 1
+fi
diff --git a/recipes-containers/vcontainer/files/vrunner.sh b/recipes-containers/vcontainer/files/vrunner.sh
index aaaaeb61..3f0b3448 100755
--- a/recipes-containers/vcontainer/files/vrunner.sh
+++ b/recipes-containers/vcontainer/files/vrunner.sh
@@ -515,6 +515,13 @@ if [ ! -f "$HV_BACKEND" ]; then
 fi
 source "$HV_BACKEND"
 
+# Xen backend uses vxn-init.sh which is a unified init (no Docker/Podman
+# daemon in guest). It always parses docker_* kernel parameters regardless
+# of which frontend (vdkr/vpdmn) invoked us.
+if [ "$VCONTAINER_HYPERVISOR" = "xen" ]; then
+    CMDLINE_PREFIX="docker"
+fi
+
 # Daemon mode handling
 # Set default socket directory based on architecture
 # If --state-dir was provided, use it for daemon files too
diff --git a/recipes-containers/vcontainer/files/vxn-oci-runtime b/recipes-containers/vcontainer/files/vxn-oci-runtime
index 57144aea..02b94fb5 100644
--- a/recipes-containers/vcontainer/files/vxn-oci-runtime
+++ b/recipes-containers/vcontainer/files/vxn-oci-runtime
@@ -37,18 +37,32 @@ BLOB_DIR="/usr/share/vxn"
 LOG_FILE="/var/log/vxn-oci-runtime.log"
 VXN_LOG="/var/log/vxn-oci-runtime.log"
 
+# Write a JSON log entry to the shim's --log file (runc-compatible format).
+# containerd-shim-runc-v2 parses this to extract error messages on failure.
+_log_json() {
+    local level="$1" msg="$2" dest="$3"
+    local ts
+    ts=$(date -u '+%Y-%m-%dT%H:%M:%SZ' 2>/dev/null || echo "1970-01-01T00:00:00Z")
+    printf '{"level":"%s","msg":"%s","time":"%s"}\n' "$level" "$msg" "$ts" >> "$dest" 2>/dev/null || true
+}
+
 log() {
     local ts
     ts=$(date '+%Y-%m-%d %H:%M:%S' 2>/dev/null || echo "-")
-    # Always write to our own log (shim overrides LOG_FILE via --log)
+    # Always write plain text to our own log for human debugging
     echo "[$ts] $*" >> "$VXN_LOG" 2>/dev/null || true
+    # Write JSON to shim's log file (if different from our log)
     if [ "$LOG_FILE" != "$VXN_LOG" ]; then
-        echo "[$ts] $*" >> "$LOG_FILE" 2>/dev/null || true
+        _log_json "info" "$*" "$LOG_FILE"
     fi
 }
 
 die() {
     log "FATAL: $*"
+    # Write JSON error to shim log so Docker can extract the message
+    if [ "$LOG_FILE" != "$VXN_LOG" ]; then
+        _log_json "error" "$*" "$LOG_FILE"
+    fi
     echo "vxn-oci-runtime: $*" >&2
     exit 1
 }
@@ -200,10 +214,26 @@ cmd_create() {
 
     log "  entrypoint='$entrypoint' cwd='$cwd' terminal=$terminal"
 
-    # Create ext4 disk image from bundle/rootfs/
-    local rootfs_dir="$bundle/rootfs"
+    # Read rootfs path from config.json (OCI spec: root.path)
+    local rootfs_path=""
+    if command -v jq >/dev/null 2>&1; then
+        rootfs_path=$(jq -r '.root.path // "rootfs"' "$config" 2>/dev/null)
+    else
+        rootfs_path=$(grep -o '"path"[[:space:]]*:[[:space:]]*"[^"]*"' "$config" 2>/dev/null | \
+            head -1 | sed 's/.*"path"[[:space:]]*:[[:space:]]*"//;s/"$//')
+        [ -z "$rootfs_path" ] && rootfs_path="rootfs"
+    fi
+    # Resolve relative paths against bundle directory
+    case "$rootfs_path" in
+        /*) ;;
+        *)  rootfs_path="$bundle/$rootfs_path" ;;
+    esac
+
+    local rootfs_dir="$rootfs_path"
     local input_img="$dir/input.img"
 
+    log "  rootfs_dir=$rootfs_dir"
+
     if [ -d "$rootfs_dir" ] && [ -n "$(ls -A "$rootfs_dir" 2>/dev/null)" ]; then
         # Calculate size: rootfs size + 50% headroom, minimum 64MB
         local rootfs_size_kb
@@ -213,8 +243,14 @@ cmd_create() {
 
         log "  Creating ext4 image: ${img_size_kb}KB from $rootfs_dir"
         mke2fs -t ext4 -d "$rootfs_dir" -b 4096 "$input_img" "${img_size_kb}K" \
-            >> "$LOG_FILE" 2>&1 || die "create: failed to create ext4 image"
+            >> "$VXN_LOG" 2>&1 || die "create: failed to create ext4 image"
     else
+        # Diagnostics: log what we actually see
+        log "  DIAG: bundle contents: $(ls -la "$bundle/" 2>&1)"
+        log "  DIAG: rootfs_dir exists=$([ -d "$rootfs_dir" ] && echo yes || echo no)"
+        log "  DIAG: rootfs_dir contents: $(ls -la "$rootfs_dir" 2>&1)"
+        log "  DIAG: mounts at bundle: $(mount 2>/dev/null | grep "$(dirname "$bundle")" || echo none)"
+        log "  DIAG: config.json root: $(grep -o '"root"[^}]*}' "$config" 2>/dev/null)"
         die "create: $rootfs_dir is empty or does not exist"
     fi
 
@@ -271,7 +307,7 @@ XENEOF
     log "  Xen config written to $config_cfg"
 
     # Create domain in paused state (OCI spec: create does not start)
-    xl create -p "$config_cfg" >> "$LOG_FILE" 2>&1 || die "create: xl create -p failed"
+    xl create -p "$config_cfg" >> "$VXN_LOG" 2>&1 || die "create: xl create -p failed"
 
     log "  Domain $domname created (paused)"
 
@@ -327,33 +363,54 @@ DBGEOF
 
     # Monitor process: tracks domain lifecycle and captures output.
     #
-    # Non-terminal mode: xl console captures the domain's serial output.
-    # When the domain dies, xl console exits (PTY closes). We immediately
-    # extract content between OUTPUT_START/END markers and write to stdout.
-    # stdout is the shim's pipe → containerd copies to client FIFO → ctr.
+    # The shim monitors the PID written to --pid-file. The monitor MUST stay
+    # alive through the full create→start→run→exit lifecycle. If the monitor
+    # dies before start is called, the shim skips start and goes to cleanup.
+    #
+    # Non-terminal mode: we poll xl list to wait for the domain to be
+    # unpaused and to run to completion. Once the domain dies, we attach
+    # xl console to read the console ring buffer, extract OUTPUT_START/END
+    # markers, and relay the output to stdout (the shim's pipe).
     #
-    # CRITICAL: We use "wait" on xl console instead of polling xl list.
-    # Polling with sleep 5 was too slow — the shim detected "stopped" and
-    # killed the monitor before it had a chance to output. Using wait gives
-    # us instant reaction when the domain dies.
+    # IMPORTANT: We cannot run xl console on a paused domain — it exits
+    # immediately with no output. Instead we wait for the domain to finish,
+    # then read the console ring buffer post-mortem via xl console -r (dmesg).
+    # However, xl console on a destroyed domain also fails. So we use a
+    # two-phase approach: poll for domain to start running, then attach
+    # xl console which will block until the domain dies.
     #
     # Terminal mode (console-socket): the shim owns the PTY exclusively.
     # We just wait for the domain to exit without capturing console.
     local _dn="$domname" _logdir="$logdir" _csock="$console_socket"
     (
         if [ -z "$_csock" ]; then
-            # Non-terminal: capture console to persistent log dir
-            xl console "$_dn" > "$_logdir/console.log" 2>&1 &
-            _cpid=$!
-
-            # Wait for xl console to exit — domain death closes the PTY,
-            # which causes xl console to exit immediately. No polling delay.
-            wait $_cpid 2>/dev/null
-
-            # Extract output between markers and write to stdout.
-            # stdout IS the shim's pipe (confirmed: fd1=pipe). The shim's
-            # io.Copy goroutine reads from this pipe and writes to the
-            # containerd client FIFO. ctr reads from the FIFO.
+            # Non-terminal: stay alive until domain finishes, then capture output.
+            #
+            # Phase 1: Wait for domain to exist and be unpaused (start called).
+            # The domain is created paused — xl console would exit immediately.
+            # Poll until it transitions from 'p' (paused) to running, or dies.
+            while xl list "$_dn" >/dev/null 2>&1; do
+                # Check if domain is still paused
+                local _state
+                _state=$(xl list "$_dn" 2>/dev/null | awk -v dn="$_dn" '$1 == dn {print $5}')
+                # States: r=running, b=blocked, p=paused, s=shutdown, c=crashed, d=dying
+                case "$_state" in
+                    p) sleep 0.2; continue ;;  # Still paused, keep waiting
+                    *)  break ;;               # Running/blocked/other — proceed
+                esac
+            done
+
+            # Phase 2: Domain is running (or already dead). Attach xl console
+            # to capture serial output. xl console blocks until PTY closes
+            # (domain death), then exits.
+            if xl list "$_dn" >/dev/null 2>&1; then
+                xl console "$_dn" > "$_logdir/console.log" 2>&1 || true
+            fi
+
+            # Phase 3: Extract output between markers and write to stdout.
+            # stdout IS the shim's pipe (fd1=pipe). The shim's io.Copy
+            # goroutine reads from this pipe and writes to the containerd
+            # client FIFO. ctr reads from the FIFO.
             if [ -f "$_logdir/console.log" ]; then
                 _relay=false
                 while IFS= read -r _line; do
@@ -409,7 +466,7 @@ cmd_start() {
     xl list "$domname" >/dev/null 2>&1 || die "start: domain $domname not found"
 
     # Unpause the domain
-    xl unpause "$domname" >> "$LOG_FILE" 2>&1 || die "start: xl unpause failed"
+    xl unpause "$domname" >> "$VXN_LOG" 2>&1 || die "start: xl unpause failed"
 
     # Update state
     local pid bundle created
@@ -462,11 +519,30 @@ EOF
 }
 
 cmd_kill() {
-    local container_id="$1"
-    local signal="${2:-SIGTERM}"
+    local container_id=""
+    local signal="SIGTERM"
+    local kill_all=false
+
+    # Parse arguments: runc accepts `kill [flags] <container-id> [signal]`
+    # Docker sends: kill --all <container-id> <signal>
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --all|-a)    kill_all=true; shift ;;
+            -*)          shift ;;  # skip unknown flags
+            *)
+                if [ -z "$container_id" ]; then
+                    container_id="$1"
+                else
+                    signal="$1"
+                fi
+                shift
+                ;;
+        esac
+    done
+
     [ -n "$container_id" ] || die "kill: container ID required"
 
-    log "KILL: id=$container_id signal=$signal"
+    log "KILL: id=$container_id signal=$signal all=$kill_all"
     load_state "$container_id"
 
     local dir
@@ -477,24 +553,24 @@ cmd_kill() {
     # Normalize signal: accept both numeric and symbolic forms
     case "$signal" in
         9|SIGKILL|KILL)
-            xl destroy "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl destroy "$domname" >> "$VXN_LOG" 2>&1 || true
             ;;
         2|SIGINT|INT)
-            xl destroy "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl destroy "$domname" >> "$VXN_LOG" 2>&1 || true
             ;;
         15|SIGTERM|TERM|"")
-            xl shutdown "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl shutdown "$domname" >> "$VXN_LOG" 2>&1 || true
             # Wait briefly for graceful shutdown, then force destroy
             local i
             for i in 1 2 3 4 5 6 7 8 9 10; do
                 xl list "$domname" >/dev/null 2>&1 || break
                 sleep 1
             done
-            xl destroy "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl destroy "$domname" >> "$VXN_LOG" 2>&1 || true
             ;;
         *)
             # Unknown signal — treat as SIGTERM
-            xl shutdown "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl shutdown "$domname" >> "$VXN_LOG" 2>&1 || true
             ;;
     esac
 
@@ -542,7 +618,7 @@ cmd_delete() {
         local domname
         domname=$(cat "$dir/domname")
         if xl list "$domname" >/dev/null 2>&1; then
-            xl destroy "$domname" >> "$LOG_FILE" 2>&1 || true
+            xl destroy "$domname" >> "$VXN_LOG" 2>&1 || true
         fi
     fi
 
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>
+```
diff --git a/recipes-core/vxn/vxn_1.0.bb b/recipes-core/vxn/vxn_1.0.bb
index d16cbc77..a08dac09 100644
--- a/recipes-core/vxn/vxn_1.0.bb
+++ b/recipes-core/vxn/vxn_1.0.bb
@@ -67,6 +67,8 @@ SRC_URI = "\
     file://containerd-config-vxn.toml \
     file://containerd-shim-vxn-v2 \
     file://vctr \
+    file://vdkr.sh \
+    file://vpdmn.sh \
 "
 
 FILESEXTRAPATHS:prepend := "${THISDIR}/../../recipes-containers/vcontainer/files:"
@@ -221,6 +223,24 @@ do_install() {
     # Install vctr convenience wrapper
     install -m 0755 ${S}/vctr ${D}${bindir}/vctr
 
+    # Docker/Podman CLI frontends (sub-packages)
+    install -m 0755 ${S}/vdkr.sh ${D}${bindir}/vdkr
+    install -m 0755 ${S}/vpdmn.sh ${D}${bindir}/vpdmn
+
+    # Docker daemon config: register vxn-oci-runtime (vxn-docker-config sub-package)
+    # no-new-privileges=false is needed because vxn ignores Linux security features.
+    # Users must use --network=none or --network=host with vxn containers since
+    # Xen DomUs have their own kernel network stack and Docker's veth/namespace
+    # setup is incompatible with VM-based runtimes.
+    install -d ${D}${sysconfdir}/docker
+    printf '{\n  "runtimes": {\n    "vxn": {\n      "path": "/usr/bin/vxn-oci-runtime"\n    }\n  },\n  "default-runtime": "vxn"\n}\n' \
+        > ${D}${sysconfdir}/docker/daemon.json
+
+    # Podman config: register vxn-oci-runtime (vxn-podman-config sub-package)
+    install -d ${D}${sysconfdir}/containers/containers.conf.d
+    printf '[engine]\nruntime = "vxn"\n\n[engine.runtimes]\nvxn = ["/usr/bin/vxn-oci-runtime"]\n' \
+        > ${D}${sysconfdir}/containers/containers.conf.d/50-vxn-runtime.conf
+
     # Install shared scripts into libdir
     install -d ${D}${libdir}/vxn
     install -m 0755 ${S}/vrunner.sh ${D}${libdir}/vxn/
@@ -253,6 +273,22 @@ do_install() {
     fi
 }
 
+# Sub-packages for CLI frontends and native runtime config
+PACKAGES =+ "${PN}-vdkr ${PN}-vpdmn ${PN}-docker-config ${PN}-podman-config"
+
+FILES:${PN}-vdkr = "${bindir}/vdkr"
+FILES:${PN}-vpdmn = "${bindir}/vpdmn"
+FILES:${PN}-docker-config = "${sysconfdir}/docker/daemon.json"
+FILES:${PN}-podman-config = "${sysconfdir}/containers/containers.conf.d/50-vxn-runtime.conf"
+
+RDEPENDS:${PN}-vdkr = "${PN} bash"
+RDEPENDS:${PN}-vpdmn = "${PN} bash"
+RDEPENDS:${PN}-docker-config = "${PN} docker"
+RDEPENDS:${PN}-podman-config = "${PN} podman"
+
+# daemon.json conflicts with docker-registry-config (only one provider)
+RCONFLICTS:${PN}-docker-config = "docker-registry-config"
+
 FILES:${PN} = "\
     ${bindir}/vxn \
     ${bindir}/vxn-oci-runtime \