12 files changed, 696 insertions, 76 deletions

diff --git a/recipes-containers/vcontainer/README.md b/recipes-containers/vcontainer/README.md
index 76d54d18..e44616f4 100644
--- a/recipes-containers/vcontainer/README.md
+++ b/recipes-containers/vcontainer/README.md
@@ -268,6 +268,109 @@ vdkr pull alpine:latest
 vdkr images   # Shows alpine:latest
 ```
 
+## Registry Login and Configuration
+
+For authenticated registries:
+
+```bash
+# Login (interactive password prompt)
+vdkr login --username myuser https://registry.example.com/
+
+# Pull from the registry
+vdkr pull registry.example.com/myimage:latest
+```
+
+Set a default registry so you don't need to specify the full URL each time:
+
+```bash
+# Set default registry (persisted across sessions)
+vdkr vconfig registry registry.example.com
+
+# Now pulls try the default registry first, then Docker Hub
+vdkr pull myimage:latest
+
+# One-off override without changing the default
+vdkr --registry other.registry.com pull myimage:latest
+
+# Clear default registry
+vdkr vconfig registry --reset
+```
+
+**Note:** The `--registry` flag is a vdkr option that sets the default
+registry for pulls. For `login`, pass the registry URL as a positional
+argument after the login flags:
+
+```bash
+# Correct:
+vdkr login --username myuser https://registry.example.com/
+
+# Wrong (--registry is consumed by vdkr, login gets no URL):
+vdkr --registry https://registry.example.com/ login --username myuser
+```
+
+**TLS certificates:** The vdkr/vpdmn rootfs images include common
+intermediate certificates (Let's Encrypt E8/R11) to handle registries
+that don't send the full certificate chain. For self-signed registries,
+use `--secure-registry --ca-cert`:
+
+```bash
+vdkr --secure-registry --ca-cert /path/to/ca.crt pull myimage
+```
+
+### Passing an existing docker/podman auth file (`--config`)
+
+If you already have credentials set up on the host (for example, from
+running `docker login` locally), you can pass the resulting auth file
+straight through into the emulated environment instead of re-entering
+credentials with `--registry-user`/`--registry-pass`:
+
+```bash
+# Docker (vdkr): uses ~/.docker/config.json by default
+vdkr --config ~/.docker/config.json pull registry.example.com/myimage
+
+# Podman (vpdmn): uses $XDG_RUNTIME_DIR/containers/auth.json
+vpdmn --config $XDG_RUNTIME_DIR/containers/auth.json pull registry.example.com/myimage
+```
+
+The path can also be supplied via environment:
+
+```bash
+export VDKR_CONFIG=$HOME/.docker/config.json
+vdkr pull registry.example.com/myimage
+```
+
+(`VPDMN_CONFIG` is honoured identically by `vpdmn`.)
+
+**What the file ends up as inside the VM:**
+
+| Tool  | Target path                       | Notes                                             |
+| ----- | --------------------------------- | ------------------------------------------------- |
+| vdkr  | `/root/.docker/config.json`       | Mode 0600; containing dir 0700                    |
+| vpdmn | `/run/containers/0/auth.json`     | Mode 0600; `$REGISTRY_AUTH_FILE` exported         |
+
+**Security model.** The credential file is treated as secret material:
+
+- The host-side file **must** be a regular file with mode `0600` or `0400`.
+  World/group-readable files are rejected outright. Symlinks are rejected.
+  Files larger than 1 MiB are rejected.
+- On the host it is copied into a per-invocation private directory under
+  `$TMPDIR/vdkr-$$/auth_share` (mode 0700; file mode 0400) and removed
+  automatically by the `EXIT`/`INT`/`TERM` trap when `vrunner.sh` exits.
+- It is exposed to the guest on a **dedicated** virtio-9p share whose
+  mount tag (`vdkr_auth` / `vpdmn_auth`) is distinct from the general
+  `*_share` share used for input/output. The guest mounts it **read-only**
+  at `/mnt/auth`, copies it into the runtime's credential location, then
+  **unmounts** `/mnt/auth` so nothing in the VM retains an open reference
+  to the host staging directory.
+- Nothing about the file appears on the kernel command line. Only a
+  boolean flag (`docker_auth=1` / `podman_auth=1`) is passed so the guest
+  init script knows to look on the auth share.
+- When both `--config` and `--registry-user`/`--registry-pass` are
+  supplied, `--config` wins and a NOTE is logged.
+- `--config` is NOT forwarded into container workloads (it only reaches
+  the container engine's credential store); containers themselves never
+  see `/mnt/auth`.
+
 ## Volume Mounts
 
 Mount host directories into containers using `-v` (requires memory resident mode):
diff --git a/recipes-containers/vcontainer/files/vcontainer-common.sh b/recipes-containers/vcontainer/files/vcontainer-common.sh
index c7160860..f389941c 100755
--- a/recipes-containers/vcontainer/files/vcontainer-common.sh
+++ b/recipes-containers/vcontainer/files/vcontainer-common.sh
@@ -327,40 +327,54 @@ normalize_arch_from_oci() {
     esac
 }
 
-# Check if OCI directory contains a multi-architecture Image Index
-# Usage: is_oci_image_index <oci_dir>
-# Returns: 0 if multi-arch, 1 if single-arch or not OCI
-is_oci_image_index() {
+# Resolve the file containing platform manifests in an OCI directory.
+# Handles two layouts:
+#   Flat:   index.json directly contains manifests with platform info
+#   Nested: index.json → single image index blob → platform manifests
+#           (skopeo-compatible format)
+# Usage: _resolve_oci_platform_file <oci_dir>
+# Prints: path to the file containing platform manifests, or empty
+_resolve_oci_platform_file() {
     local oci_dir="$1"
 
     [ -f "$oci_dir/index.json" ] || return 1
 
-    # Check if index.json has manifests with platform info
-    # Multi-arch images have "platform" object in manifest entries
+    # Flat layout: platform info directly in index.json
     if grep -q '"platform"' "$oci_dir/index.json" 2>/dev/null; then
-        # Also verify there are multiple manifests
-        local manifest_count=$(grep -c '"digest"' "$oci_dir/index.json" 2>/dev/null || echo "0")
-        [ "$manifest_count" -gt 1 ] && return 0
-
-        # Single manifest with platform info is also a valid Image Index
-        # (could be a multi-arch image built with only one arch so far)
+        echo "$oci_dir/index.json"
         return 0
     fi
 
+    # Nested layout: index.json has a single entry with image.index mediaType
+    if grep -q 'image\.index' "$oci_dir/index.json" 2>/dev/null; then
+        local index_digest=$(grep -o '"sha256:[a-f0-9]*"' "$oci_dir/index.json" 2>/dev/null | head -1 | tr -d '"' | sed 's/sha256://')
+        if [ -n "$index_digest" ] && [ -f "$oci_dir/blobs/sha256/$index_digest" ]; then
+            if grep -q '"platform"' "$oci_dir/blobs/sha256/$index_digest" 2>/dev/null; then
+                echo "$oci_dir/blobs/sha256/$index_digest"
+                return 0
+            fi
+        fi
+    fi
+
     return 1
 }
 
+# Check if OCI directory contains a multi-architecture Image Index
+# Usage: is_oci_image_index <oci_dir>
+# Returns: 0 if multi-arch, 1 if single-arch or not OCI
+is_oci_image_index() {
+    _resolve_oci_platform_file "$1" >/dev/null 2>&1
+}
+
 # Get list of available platforms in a multi-arch OCI Image Index
 # Usage: get_oci_platforms <oci_dir>
 # Returns: Space-separated list of architectures (e.g., "arm64 amd64")
 get_oci_platforms() {
     local oci_dir="$1"
+    local platform_file
+    platform_file=$(_resolve_oci_platform_file "$oci_dir") || return 1
 
-    [ -f "$oci_dir/index.json" ] || return 1
-
-    # Extract architecture values from platform objects
-    # Format: "platform": { "architecture": "arm64", "os": "linux" }
-    grep -o '"architecture"[[:space:]]*:[[:space:]]*"[^"]*"' "$oci_dir/index.json" 2>/dev/null | \
+    grep -o '"architecture"[[:space:]]*:[[:space:]]*"[^"]*"' "$platform_file" 2>/dev/null | \
         sed 's/.*"\([^"]*\)"$/\1/' | \
         tr '\n' ' ' | sed 's/ $//'
 }
@@ -373,38 +387,34 @@ select_platform_manifest() {
     local oci_dir="$1"
     local target_arch="$2"
 
-    [ -f "$oci_dir/index.json" ] || return 1
-
     # Normalize target arch to OCI convention
     local oci_arch=$(normalize_arch_to_oci "$target_arch")
 
-    # Parse index.json to find manifest with matching platform
+    # Resolve the file containing platform manifests (flat or nested)
+    local manifest_index
+    manifest_index=$(_resolve_oci_platform_file "$oci_dir") || return 1
+
+    # Parse the manifest index to find manifest with matching platform
     # This is done without jq using grep/sed for portability
     local in_manifest=0
     local current_digest=""
     local current_arch=""
     local matched_digest=""
 
-    # Read index.json line by line
     while IFS= read -r line; do
-        # Track when we're inside a manifest entry
         if echo "$line" | grep -q '"manifests"'; then
             in_manifest=1
             continue
         fi
 
         if [ "$in_manifest" = "1" ]; then
-            # Extract digest
             if echo "$line" | grep -q '"digest"'; then
                 current_digest=$(echo "$line" | sed 's/.*"sha256:\([a-f0-9]*\)".*/\1/')
             fi
 
-            # Extract architecture from platform
-            # Handle both formats: "architecture": "arm64" or {"architecture": "arm64", ...}
             if echo "$line" | grep -q '"architecture"'; then
                 current_arch=$(echo "$line" | sed 's/.*"architecture"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
 
-                # Check if this matches our target
                 if [ "$current_arch" = "$oci_arch" ]; then
                     matched_digest="$current_digest"
                     OCI_SELECTED_PLATFORM="$current_arch"
@@ -412,13 +422,12 @@ select_platform_manifest() {
                 fi
             fi
 
-            # Reset on closing brace (end of manifest entry)
             if echo "$line" | grep -q '^[[:space:]]*}'; then
                 current_digest=""
                 current_arch=""
             fi
         fi
-    done < "$oci_dir/index.json"
+    done < "$manifest_index"
 
     if [ -n "$matched_digest" ]; then
         echo "$matched_digest"
@@ -718,6 +727,11 @@ ${BOLD}GLOBAL OPTIONS:${NC}
     --registry <url>      Default registry for unqualified images (e.g., 10.0.2.2:5000/yocto)
     --no-registry         Disable baked-in default registry (use images as-is)
     --insecure-registry <host:port>  Mark registry as insecure (HTTP). Can repeat.
+    --config <path>       Registry auth file (docker config.json / podman auth.json)
+                          Defaults to \$VDKR_CONFIG / \$VPDMN_CONFIG. The file must be
+                          mode 0600 or stricter; it is passed to the guest over a
+                          dedicated read-only virtio-9p share and never appears on
+                          the kernel cmdline.
     --verbose, -v         Enable verbose output
     --help, -h            Show this help
 
@@ -857,6 +871,7 @@ build_runner_args() {
     [ -n "$CA_CERT" ] && args+=("--ca-cert" "$CA_CERT")
     [ -n "$REGISTRY_USER" ] && args+=("--registry-user" "$REGISTRY_USER")
     [ -n "$REGISTRY_PASS" ] && args+=("--registry-pass" "$REGISTRY_PASS")
+    [ -n "$AUTH_CONFIG" ] && args+=("--config" "$AUTH_CONFIG")
 
     # Xen: pass exit grace period
     [ -n "${VXN_EXIT_GRACE_PERIOD:-}" ] && args+=("--exit-grace-period" "$VXN_EXIT_GRACE_PERIOD")
@@ -880,6 +895,11 @@ SECURE_REGISTRY="false"
 CA_CERT=""
 REGISTRY_USER=""
 REGISTRY_PASS=""
+# Registry auth config file. Env-var default depends on which CLI wrapper is
+# in use (vdkr → $VDKR_CONFIG, vpdmn → $VPDMN_CONFIG), then falls back to the
+# other for convenience when sharing a single host-side file. Overridden by
+# the --config CLI flag below.
+AUTH_CONFIG="${VDKR_CONFIG:-${VPDMN_CONFIG:-}}"
 COMMAND=""
 COMMAND_ARGS=()
 
@@ -977,6 +997,13 @@ while [ $# -gt 0 ]; do
             REGISTRY_PASS="$2"
             shift 2
             ;;
+        --config)
+            # Path to a docker/podman registry auth file (config.json / auth.json).
+            # Overrides $VDKR_CONFIG / $VPDMN_CONFIG. Forwarded to vrunner.sh --config,
+            # which validates the file and stages it on a dedicated read-only 9p share.
+            AUTH_CONFIG="$2"
+            shift 2
+            ;;
         -it|--interactive)
             INTERACTIVE="true"
             shift
@@ -1858,11 +1885,11 @@ case "$COMMAND" in
 
                 # Check for multi-architecture OCI Image Index
                 if is_oci_image_index "$INPUT_PATH"; then
-                    local available_platforms=$(get_oci_platforms "$INPUT_PATH")
+                    available_platforms=$(get_oci_platforms "$INPUT_PATH")
                     [ "$VERBOSE" = "true" ] && echo -e "${CYAN}[$VCONTAINER_RUNTIME_NAME]${NC} Multi-arch OCI detected. Available: $available_platforms" >&2
 
                     # Select manifest for target architecture
-                    local manifest_digest=$(select_platform_manifest "$INPUT_PATH" "$TARGET_ARCH")
+                    manifest_digest=$(select_platform_manifest "$INPUT_PATH" "$TARGET_ARCH")
                     if [ -z "$manifest_digest" ]; then
                         echo -e "${RED}[$VCONTAINER_RUNTIME_NAME]${NC} Architecture $TARGET_ARCH not found in multi-arch image" >&2
                         echo -e "${YELLOW}[$VCONTAINER_RUNTIME_NAME]${NC} Available platforms: $available_platforms" >&2
@@ -1870,7 +1897,7 @@ case "$COMMAND" in
                         exit 1
                     fi
 
-                    echo -e "${GREEN}[$VCONTAINER_RUNTIME_NAME]${NC} Selected platform: $OCI_SELECTED_PLATFORM (from multi-arch image)" >&2
+                    echo -e "${GREEN}[$VCONTAINER_RUNTIME_NAME]${NC} Selected platform: $(normalize_arch_to_oci "$TARGET_ARCH")/linux (from multi-arch image)" >&2
 
                     # Extract single-platform OCI to temp directory
                     TEMP_OCI_DIR=$(mktemp -d)
@@ -2196,9 +2223,14 @@ case "$COMMAND" in
 
     login)
         [ "${VCONTAINER_HYPERVISOR:-}" = "xen" ] && vxn_unsupported "login"
-        # Login to registry - may need credentials via stdin
-        # For non-interactive: runtime login -u user -p pass registry
-        run_runtime_command "$VCONTAINER_RUNTIME_CMD login ${COMMAND_ARGS[*]}"
+        # Login needs interactive stdin for password prompt.
+        # Use daemon-interactive mode (same as vshell/exec -it).
+        if daemon_is_running; then
+            RUNNER_ARGS=$(build_runner_args)
+            "$RUNNER" $RUNNER_ARGS --daemon-interactive -- "$VCONTAINER_RUNTIME_CMD login ${COMMAND_ARGS[*]}"
+        else
+            run_runtime_command "$VCONTAINER_RUNTIME_CMD login ${COMMAND_ARGS[*]}"
+        fi
         ;;
 
     logout)
@@ -2483,12 +2515,20 @@ case "$COMMAND" in
             STORAGE_CMD="${COMMAND_ARGS[0]}"
         fi
 
+        # When --state-dir is passed, scan its parent as the storage root
+        # (STATE_DIR is an arch subdir like ~/.vpdmn-test/x86_64, so the
+        # parent ~/.vpdmn-test/ is the root containing all arch dirs).
+        VSTORAGE_ROOT="$DEFAULT_STATE_DIR"
+        if [ -n "$STATE_DIR" ]; then
+            VSTORAGE_ROOT="$(dirname "$STATE_DIR")"
+        fi
+
         case "$STORAGE_CMD" in
             list)
                 echo "$VCONTAINER_RUNTIME_NAME storage directories:"
                 echo ""
                 found=0
-                for state_dir in "$DEFAULT_STATE_DIR"/*/; do
+                for state_dir in "$VSTORAGE_ROOT"/*/; do
                     [ -d "$state_dir" ] || continue
                     found=1
                     instance=$(basename "$state_dir")
@@ -2517,8 +2557,8 @@ case "$COMMAND" in
                 fi
 
                 # Total size
-                if [ -d "$DEFAULT_STATE_DIR" ] && [ $found -gt 0 ]; then
-                    total=$(du -sh "$DEFAULT_STATE_DIR" 2>/dev/null | cut -f1)
+                if [ -d "$VSTORAGE_ROOT" ] && [ $found -gt 0 ]; then
+                    total=$(du -sh "$VSTORAGE_ROOT" 2>/dev/null | cut -f1)
                     echo "Total: $total"
                 fi
                 ;;
@@ -2531,7 +2571,7 @@ case "$COMMAND" in
 
             df)
                 # Detailed breakdown
-                for state_dir in "$DEFAULT_STATE_DIR"/*/; do
+                for state_dir in "$VSTORAGE_ROOT"/*/; do
                     [ -d "$state_dir" ] || continue
                     instance=$(basename "$state_dir")
                     echo "${BOLD}$instance${NC}:"
@@ -2552,7 +2592,7 @@ case "$COMMAND" in
                 arch="${COMMAND_ARGS[1]:-}"
                 if [ "$arch" = "--all" ]; then
                     # Stop any running memres first
-                    for pid_file in "$DEFAULT_STATE_DIR"/*/daemon.pid; do
+                    for pid_file in "$VSTORAGE_ROOT"/*/daemon.pid; do
                         [ -f "$pid_file" ] || continue
                         pid=$(cat "$pid_file" 2>/dev/null)
                         if [ -n "$pid" ] && [ -d "/proc/$pid" ]; then
@@ -2561,11 +2601,11 @@ case "$COMMAND" in
                         fi
                     done
                     echo -e "${YELLOW}[$VCONTAINER_RUNTIME_NAME]${NC} Removing all storage directories..."
-                    rm -rf "$DEFAULT_STATE_DIR"
+                    rm -rf "$VSTORAGE_ROOT"
                     echo -e "${GREEN}[$VCONTAINER_RUNTIME_NAME]${NC} All storage cleaned."
                 elif [ -n "$arch" ]; then
                     # Clean specific arch
-                    clean_dir="$DEFAULT_STATE_DIR/$arch"
+                    clean_dir="$VSTORAGE_ROOT/$arch"
                     if [ -d "$clean_dir" ]; then
                         # Stop memres if running
                         if [ -f "$clean_dir/daemon.pid" ]; then
diff --git a/recipes-containers/vcontainer/files/vcontainer-init-common.sh b/recipes-containers/vcontainer/files/vcontainer-init-common.sh
index ab8762b2..3bd70e75 100755
--- a/recipes-containers/vcontainer/files/vcontainer-init-common.sh
+++ b/recipes-containers/vcontainer/files/vcontainer-init-common.sh
@@ -156,6 +156,7 @@ parse_cmdline() {
     RUNTIME_INTERACTIVE="0"
     RUNTIME_DAEMON="0"
     RUNTIME_9P="0"  # virtio-9p available for fast I/O
+    RUNTIME_AUTH="0"  # registry auth config (config.json / auth.json) available on dedicated 9p share
     RUNTIME_IDLE_TIMEOUT="1800"  # Default: 30 minutes
 
     for param in $(cat /proc/cmdline); do
@@ -187,6 +188,9 @@ parse_cmdline() {
             ${VCONTAINER_RUNTIME_PREFIX}_9p=*)
                 RUNTIME_9P="${param#${VCONTAINER_RUNTIME_PREFIX}_9p=}"
                 ;;
+            ${VCONTAINER_RUNTIME_PREFIX}_auth=*)
+                RUNTIME_AUTH="${param#${VCONTAINER_RUNTIME_PREFIX}_auth=}"
+                ;;
         esac
     done
 
@@ -263,6 +267,56 @@ mount_input_disk() {
 }
 
 # ============================================================================
+# Registry auth share (docker config.json / podman auth.json)
+# ============================================================================
+# The host stages a validated credential file on a *dedicated* read-only 9p
+# share tagged "${VCONTAINER_RUNTIME_NAME}_auth" (e.g. "vdkr_auth" or
+# "vpdmn_auth"). That tag is separate from the general ${VCONTAINER_SHARE_NAME}
+# used for input/output so credentials can't leak into storage.tar outputs or
+# be overwritten by daemon_send_with_input.
+#
+# We mount read-only, nosuid, nodev, noexec at /mnt/auth. Callers are expected
+# to copy the credential file into the runtime's canonical location with
+# restrictive permissions and then call unmount_auth_share() so the guest
+# filesystem no longer has an open reference to the host-side file.
+
+AUTH_SHARE_TAG=""
+AUTH_SHARE_MOUNT="/mnt/auth"
+
+mount_auth_share() {
+    if [ "$RUNTIME_AUTH" != "1" ]; then
+        return 1
+    fi
+
+    AUTH_SHARE_TAG="${VCONTAINER_RUNTIME_NAME}_auth"
+    mkdir -p "$AUTH_SHARE_MOUNT"
+
+    # trans/version/cache match the existing 9p share mount. Add:
+    #   ro      - guest can't mutate the host-side staging directory
+    #   nosuid  - no setuid binaries can be executed from the share
+    #   nodev   - no device nodes honoured even if crafted
+    #   noexec  - no code can execute from the share (auth.json is pure data)
+    if mount -t 9p \
+        -o trans=${NINE_P_TRANSPORT},version=9p2000.L,cache=none,ro,nosuid,nodev,noexec \
+        "$AUTH_SHARE_TAG" "$AUTH_SHARE_MOUNT" 2>/dev/null; then
+        log "Mounted auth 9p share at $AUTH_SHARE_MOUNT (tag: $AUTH_SHARE_TAG, ro)"
+        return 0
+    fi
+
+    log "WARNING: Could not mount auth 9p share ($AUTH_SHARE_TAG)"
+    RUNTIME_AUTH="0"
+    return 1
+}
+
+unmount_auth_share() {
+    if mountpoint -q "$AUTH_SHARE_MOUNT" 2>/dev/null; then
+        umount "$AUTH_SHARE_MOUNT" 2>/dev/null || \
+            umount -l "$AUTH_SHARE_MOUNT" 2>/dev/null || true
+    fi
+    rmdir "$AUTH_SHARE_MOUNT" 2>/dev/null || true
+}
+
+# ============================================================================
 # Network Configuration
 # ============================================================================
 
diff --git a/recipes-containers/vcontainer/files/vdkr-init.sh b/recipes-containers/vcontainer/files/vdkr-init.sh
index e1e869b2..4ad50668 100755
--- a/recipes-containers/vcontainer/files/vdkr-init.sh
+++ b/recipes-containers/vcontainer/files/vdkr-init.sh
@@ -26,6 +26,10 @@
 #   docker_registry_ca=1                  CA certificate available in /mnt/share/ca.crt
 #   docker_registry_user=<user>           Registry username for authentication
 #   docker_registry_pass=<base64>         Base64-encoded registry password
+#   docker_auth=1                         A pre-built docker config.json is available
+#                                         on a dedicated read-only 9p share tagged
+#                                         "vdkr_auth" (mounted at /mnt/auth). Takes
+#                                         precedence over docker_registry_user/pass.
 #
 # Version: 2.5.0
 
@@ -159,6 +163,55 @@ EOF
     fi
 }
 
+# Install a user-supplied docker config.json from the dedicated read-only
+# auth 9p share (mounted at /mnt/auth by mount_auth_share). This takes
+# precedence over credentials supplied via docker_registry_user/pass.
+#
+# Security posture:
+#   * File is read from a read-only 9p share with a separate tag ("vdkr_auth")
+#     so it cannot leak into /mnt/share outputs.
+#   * Target is written with mode 0600 and the parent dir with mode 0700.
+#   * We unmount /mnt/auth immediately after copying so neither the dockerd
+#     runtime nor user workloads in the VM have an open reference to the
+#     host-side staging directory.
+install_auth_config() {
+    if [ "$RUNTIME_AUTH" != "1" ]; then
+        return 0
+    fi
+
+    if ! mount_auth_share; then
+        log "WARNING: docker_auth=1 was set but the auth 9p share did not mount"
+        return 1
+    fi
+
+    local src="$AUTH_SHARE_MOUNT/config.json"
+    if [ ! -f "$src" ]; then
+        log "WARNING: expected $src on auth share but file is missing"
+        unmount_auth_share
+        return 1
+    fi
+
+    mkdir -p /root/.docker
+    chmod 700 /root/.docker
+
+    if cp "$src" /root/.docker/config.json 2>/dev/null; then
+        chmod 600 /root/.docker/config.json
+        log "Installed registry auth config at /root/.docker/config.json"
+        if [ -n "$DOCKER_REGISTRY_USER" ] || [ -n "$DOCKER_REGISTRY_PASS" ]; then
+            log "NOTE: --config takes precedence over --registry-user/--registry-pass"
+        fi
+    else
+        log "ERROR: failed to copy auth config to /root/.docker/config.json"
+        unmount_auth_share
+        return 1
+    fi
+
+    # Release the host-side share so credentials aren't still addressable
+    # through /mnt/auth for the lifetime of the VM.
+    unmount_auth_share
+    return 0
+}
+
 # ============================================================================
 # Docker-Specific Functions
 # ============================================================================
@@ -684,6 +737,11 @@ parse_secure_registry_config
 # Install CA certificate for secure registry
 install_registry_ca
 
+# Install user-supplied docker config.json from the dedicated auth 9p share.
+# Must run AFTER install_registry_ca so that --config takes precedence when
+# both mechanisms are used.
+install_auth_config
+
 # Start containerd and dockerd (Docker-specific)
 start_containerd
 start_dockerd
diff --git a/recipes-containers/vcontainer/files/vpdmn-init.sh b/recipes-containers/vcontainer/files/vpdmn-init.sh
index 7f661102..2036ed39 100755
--- a/recipes-containers/vcontainer/files/vpdmn-init.sh
+++ b/recipes-containers/vcontainer/files/vpdmn-init.sh
@@ -20,6 +20,12 @@
 #   podman_output=<type>   Output type: text, tar, storage (default: text)
 #   podman_state=<type>    State type: none, disk (default: none)
 #   podman_network=1       Enable networking (configure eth0, DNS)
+#   podman_auth=1          A pre-built registry auth file (docker config.json
+#                          schema, "auths" block) is available on a dedicated
+#                          read-only 9p share tagged "vpdmn_auth" (mounted at
+#                          /mnt/auth). Installed as /run/containers/0/auth.json
+#                          (the rootful podman default), and exported via
+#                          $REGISTRY_AUTH_FILE.
 #
 # Version: 1.1.0
 #
@@ -97,6 +103,57 @@ verify_podman() {
     fi
 }
 
+# Install a user-supplied registry auth file from the dedicated read-only
+# auth 9p share (mounted at /mnt/auth by mount_auth_share). Podman accepts
+# the same "auths" JSON schema as docker config.json, so we can copy directly.
+#
+# Canonical rootful path is /run/containers/0/auth.json; we also export
+# $REGISTRY_AUTH_FILE so it works regardless of podman's search order.
+#
+# Security posture matches vdkr-init.sh install_auth_config:
+#   * Source is a separate read-only 9p tag ("vpdmn_auth") so it cannot leak
+#     into /mnt/share outputs.
+#   * Target has mode 0600; containing dir has mode 0700.
+#   * /mnt/auth is unmounted immediately after copy so user workloads in the
+#     VM have no open reference to the host-side staging directory.
+install_auth_config() {
+    if [ "$RUNTIME_AUTH" != "1" ]; then
+        return 0
+    fi
+
+    if ! mount_auth_share; then
+        log "WARNING: podman_auth=1 was set but the auth 9p share did not mount"
+        return 1
+    fi
+
+    local src="$AUTH_SHARE_MOUNT/config.json"
+    if [ ! -f "$src" ]; then
+        log "WARNING: expected $src on auth share but file is missing"
+        unmount_auth_share
+        return 1
+    fi
+
+    # Rootful podman's default auth path
+    local auth_dir="/run/containers/0"
+    local auth_file="$auth_dir/auth.json"
+
+    mkdir -p "$auth_dir"
+    chmod 700 "$auth_dir"
+
+    if cp "$src" "$auth_file" 2>/dev/null; then
+        chmod 600 "$auth_file"
+        export REGISTRY_AUTH_FILE="$auth_file"
+        log "Installed registry auth config at $auth_file"
+    else
+        log "ERROR: failed to copy auth config to $auth_file"
+        unmount_auth_share
+        return 1
+    fi
+
+    unmount_auth_share
+    return 0
+}
+
 # Podman is daemonless - nothing to stop
 stop_runtime_daemons() {
     :
@@ -190,6 +247,10 @@ configure_networking
 # Verify podman is available (no daemon to start)
 verify_podman
 
+# Install user-supplied auth config from the dedicated auth 9p share, if any.
+# Done before command execution so pulls/logins have credentials available.
+install_auth_config
+
 # Handle daemon mode or single command execution
 if [ "$RUNTIME_DAEMON" = "1" ]; then
     run_daemon_mode
diff --git a/recipes-containers/vcontainer/files/vrunner-backend-qemu.sh b/recipes-containers/vcontainer/files/vrunner-backend-qemu.sh
index 87054876..3ea73cc7 100644
--- a/recipes-containers/vcontainer/files/vrunner-backend-qemu.sh
+++ b/recipes-containers/vcontainer/files/vrunner-backend-qemu.sh
@@ -188,10 +188,16 @@ hv_start_vm_background() {
     local log_file="$2"
     local timeout_val="$3"
 
+    # Fully detach stdio from the invoking shell. In daemon mode this
+    # process outlives vrunner.sh, and if the CLI that invoked us was
+    # wrapped by something that pipes stdout/stderr (e.g. a test harness
+    # using subprocess.run(capture_output=True)), any inherited fd here
+    # would block the parent's read/communicate() call until QEMU exits.
+    # Redirect fd 0 from /dev/null and fd 1/fd 2 to the log file.
     if [ -n "$timeout_val" ]; then
-        timeout $timeout_val $HV_CMD $HV_OPTS -append "$kernel_append" > "$log_file" 2>&1 &
+        timeout $timeout_val $HV_CMD $HV_OPTS -append "$kernel_append" </dev/null > "$log_file" 2>&1 &
     else
-        $HV_CMD $HV_OPTS -append "$kernel_append" > "$log_file" 2>&1 &
+        $HV_CMD $HV_OPTS -append "$kernel_append" </dev/null > "$log_file" 2>&1 &
     fi
     HV_VM_PID=$!
 }
diff --git a/recipes-containers/vcontainer/files/vrunner-backend-xen.sh b/recipes-containers/vcontainer/files/vrunner-backend-xen.sh
index 55e87bd1..f490f91c 100644
--- a/recipes-containers/vcontainer/files/vrunner-backend-xen.sh
+++ b/recipes-containers/vcontainer/files/vrunner-backend-xen.sh
@@ -397,13 +397,23 @@ hv_start_vm_background() {
         # Monitor process: stays alive while domain exists.
         # vcontainer-common.sh checks /proc/$pid → alive means daemon running.
         # When domain dies (xl destroy, guest reboot), monitor exits.
+        #
+        # Detach the monitor's stdio from the invoking shell: in daemon
+        # mode this process outlives vrunner.sh, and any inherited fd
+        # would keep a pipe-wrapped caller (e.g. subprocess.run with
+        # capture_output=True) blocked in communicate() until the domain
+        # exits. Redirect fd 0/1/2 and disown.
         local _domname="$HV_DOMNAME"
-        (while xl list "$_domname" >/dev/null 2>&1; do sleep 10; done) &
+        (while xl list "$_domname" >/dev/null 2>&1; do sleep 10; done) \
+            </dev/null >/dev/null 2>&1 &
         HV_VM_PID=$!
+        disown $! 2>/dev/null || true
     else
         # Ephemeral mode: capture guest console (hvc0) to log file
-        # so the monitoring loop in vrunner.sh can see output markers
-        stdbuf -oL xl console "$HV_DOMNAME" >> "$log_file" 2>&1 &
+        # so the monitoring loop in vrunner.sh can see output markers.
+        # Detach stdin so the background reader doesn't hold the caller's
+        # fd 0 open.
+        stdbuf -oL xl console "$HV_DOMNAME" </dev/null >> "$log_file" 2>&1 &
         _XEN_CONSOLE_PID=$!
         log "DEBUG" "Console capture started (PID: $_XEN_CONSOLE_PID)"
     fi
diff --git a/recipes-containers/vcontainer/files/vrunner.sh b/recipes-containers/vcontainer/files/vrunner.sh
index b6455330..4058fe54 100755
--- a/recipes-containers/vcontainer/files/vrunner.sh
+++ b/recipes-containers/vcontainer/files/vrunner.sh
@@ -38,6 +38,13 @@ TARGET_ARCH="${VDKR_ARCH:-${VPDMN_ARCH:-aarch64}}"
 TIMEOUT="${VDKR_TIMEOUT:-${VPDMN_TIMEOUT:-300}}"
 VERBOSE="${VDKR_VERBOSE:-${VPDMN_VERBOSE:-false}}"
 
+# Registry authentication config file (docker config.json / podman auth.json).
+# Can be set via $VDKR_CONFIG or $VPDMN_CONFIG in the environment, and is
+# overridden by the --config CLI flag below. The file is passed into the guest
+# over a dedicated read-only virtio-9p share and installed into the guest
+# container runtime's credential location by the init script.
+AUTH_CONFIG="${VDKR_CONFIG:-${VPDMN_CONFIG:-}}"
+
 # Runtime-specific settings (set after parsing --runtime)
 set_runtime_config() {
     case "$RUNTIME" in
@@ -232,6 +239,12 @@ OPTIONS:
     --network, -n        Enable networking (slirp user-mode, outbound only)
     --registry <url>     Default registry for unqualified images (e.g., 10.0.2.2:5000/yocto)
     --insecure-registry <host:port>  Mark registry as insecure (HTTP). Can repeat.
+    --config <path>      Path to docker/podman auth config (config.json / auth.json).
+                         Defaults to $VDKR_CONFIG or $VPDMN_CONFIG from environment.
+                         The file is passed to the guest over a dedicated read-only
+                         virtio-9p share and installed at /root/.docker/config.json
+                         (vdkr) or /run/containers/0/auth.json (vpdmn). The host file
+                         must be a regular file with mode 0600 or stricter.
     --interactive, -it   Run in interactive mode (connects terminal to container)
     --timeout <secs>     QEMU timeout [default: 300]
     --idle-timeout <s>   Daemon idle timeout in seconds [default: 1800]
@@ -406,6 +419,13 @@ while [ $# -gt 0 ]; do
             REGISTRY_PASS="$2"
             shift 2
             ;;
+        --config)
+            # Path to a docker/podman config file (config.json / auth.json)
+            # Overrides $VDKR_CONFIG / $VPDMN_CONFIG. The file is mounted into
+            # the guest via a dedicated read-only virtio-9p share.
+            AUTH_CONFIG="$2"
+            shift 2
+            ;;
         --interactive|-it)
             INTERACTIVE="true"
             shift
@@ -587,13 +607,63 @@ daemon_stop() {
     local pid=$(cat "$DAEMON_PID_FILE")
     log "INFO" "Stopping daemon (PID: $pid)..."
 
-    # Send shutdown command via socket
+    # Send shutdown command via socket, then poll until the VM exits.
+    #
+    # The guest's graceful_shutdown() does sync + umount of
+    # /var/lib/containers/storage + blockdev --flushbufs + sync + sleep 2
+    # + reboot -f. Under load (e.g. tens of MB of just-imported layer
+    # blobs awaiting ext4 journal commit) this routinely takes 5-30
+    # seconds. A fixed 2-second wait followed by SIGTERM kills the
+    # guest mid-umount and leaves the state disk's ext4 journal
+    # half-committed: layer files have correct inode metadata but
+    # partially-unwritten data extents, and the next session's reads
+    # hit EOF or CRC failures during tar-split layer reassembly:
+    #
+    #   Error: reading blob sha256:<hash>: EOF
+    #   Error: reading blob sha256:<hash>: file integrity checksum
+    #          failed for "<file>"
     if [ -S "$DAEMON_SOCKET" ]; then
         echo "===SHUTDOWN===" | socat - "UNIX-CONNECT:$DAEMON_SOCKET" 2>/dev/null || true
-        sleep 2
+        # Poll up to 60s (120 * 0.5s). Generous enough to cover heavy
+        # ext4 journal commits; short enough that a truly hung guest
+        # doesn't block the caller indefinitely.
+        for _i in $(seq 1 120); do
+            kill -0 "$pid" 2>/dev/null || break
+            sleep 0.5
+        done
     fi
 
-    # If still running, kill it
+    # If still running after the graceful window, the guest didn't complete
+    # its graceful_shutdown() — meaning the state disk's ext4 journal may
+    # not have committed all pending writes from this session. Any escalation
+    # from here on risks leaving the disk image partially-written: layer
+    # files with correct inode metadata but unwritten data extents, which
+    # surface as "reading blob ...: EOF" or "file integrity checksum failed"
+    # errors on the *next* session's reads. Warn loudly so the operator can
+    # decide whether to start the next session with `memres restart --clean`.
+    if kill -0 "$pid" 2>/dev/null; then
+        log "WARN" "Guest did not exit within graceful window — state disk integrity may be compromised."
+        log "WARN" "If subsequent sessions report 'reading blob ...: EOF' or 'file integrity checksum failed',"
+        log "WARN" "discard state with: ${VCONTAINER_RUNTIME_NAME:-vrunner} memres restart --clean"
+    fi
+
+    # If still running after the graceful window, escalate via QMP quit.
+    # Functionally similar to SIGTERM at the QEMU-process level (both
+    # converge on qemu_system_killed and a block-layer flush), but goes
+    # through QEMU's monitor interface — the same path hv_idle_shutdown()
+    # uses. Keeps the two escalation paths consistent.
+    if kill -0 "$pid" 2>/dev/null; then
+        local qmp_sock="$DAEMON_SOCKET_DIR/qmp.sock"
+        if [ -S "$qmp_sock" ]; then
+            log "INFO" "Sending QMP quit..."
+            echo '{"execute":"qmp_capabilities"}{"execute":"quit"}' | \
+                socat - "UNIX-CONNECT:$qmp_sock" >/dev/null 2>&1 || true
+            sleep 2
+        fi
+    fi
+
+    # If QMP quit didn't take (or no QMP socket — older configs), fall
+    # back to SIGTERM.
     if kill -0 "$pid" 2>/dev/null; then
         log "INFO" "Sending SIGTERM..."
         kill "$pid" 2>/dev/null || true
@@ -847,6 +917,124 @@ fi
 TEMP_DIR="${TMPDIR:-/tmp}/vdkr-$$"
 mkdir -p "$TEMP_DIR"
 
+# ============================================================================
+# Registry auth config (docker config.json / podman auth.json)
+# ============================================================================
+# The AUTH_CONFIG path (from $VDKR_CONFIG, $VPDMN_CONFIG, or --config) points
+# to a file containing container-registry credentials. For defence-in-depth we:
+#   * reject non-regular files (symlinks, devices, directories)
+#   * reject files readable by group/other (mode must be <= 0600)
+#   * warn if the file is not owned by the invoking user
+#   * copy it into a private per-invocation directory under $TEMP_DIR at 0400
+#   * expose it to the guest via a *separate* read-only virtio-9p tag
+#     ("${TOOL_NAME}_auth") mounted at /mnt/auth (not the generic /mnt/share
+#     which holds input/output and is wiped between daemon commands)
+#   * never pass the file contents or path on the kernel cmdline; only a flag
+#     "${CMDLINE_PREFIX}_auth=1" to tell the init script to look at /mnt/auth
+#   * rely on the existing $TEMP_DIR EXIT/INT/TERM trap to delete the copy
+#
+# The auth file is never logged (path is visible, but contents are not).
+AUTH_SHARE_DIR=""
+
+validate_auth_config() {
+    local path="$1"
+
+    # Resolve symlinks to the canonical path so the perm check applies to the
+    # actual file, but still require the *named* path to be a regular file
+    # (not a symlink pointing into sensitive areas like /proc/self/environ).
+    if [ -L "$path" ]; then
+        log "ERROR" "--config must not be a symlink: $path"
+        return 1
+    fi
+    if [ ! -e "$path" ]; then
+        log "ERROR" "--config file not found: $path"
+        return 1
+    fi
+    if [ ! -f "$path" ]; then
+        log "ERROR" "--config must be a regular file: $path"
+        return 1
+    fi
+    if [ ! -r "$path" ]; then
+        log "ERROR" "--config file is not readable: $path"
+        return 1
+    fi
+
+    # Size sanity: docker config.json / podman auth.json should be small.
+    # 1 MiB is already generous. Reject unusually large files to avoid
+    # accidentally shipping a large credential blob.
+    local size
+    size=$(stat -c %s "$path" 2>/dev/null || echo 0)
+    if [ "$size" -gt 1048576 ]; then
+        log "ERROR" "--config file is too large ($size bytes, max 1 MiB): $path"
+        return 1
+    fi
+    # Minimum valid JSON object "{}" is 2 bytes. Anything smaller (including a
+    # 0-byte truncation or a lone newline from "echo '' > file") can't be a
+    # real auth config; reject rather than silently shipping garbage.
+    if [ "$size" -lt 2 ]; then
+        log "ERROR" "--config file is empty or too small to be valid JSON: $path"
+        return 1
+    fi
+
+    # Permission check: must not be readable by group or world.
+    local mode
+    mode=$(stat -c %a "$path" 2>/dev/null || echo 0)
+    # stat %a emits octal without leading zero. Forbid any group/other bits.
+    case "$mode" in
+        400|600|200) ;;
+        *)
+            log "ERROR" "--config file has unsafe permissions ($mode); expected 0600 or 0400."
+            log "ERROR" "Fix with: chmod 600 \"$path\""
+            return 1
+            ;;
+    esac
+
+    # Ownership check: warn if file is not owned by the current user.
+    local uid owner
+    uid=$(id -u)
+    owner=$(stat -c %u "$path" 2>/dev/null || echo "")
+    if [ -n "$owner" ] && [ "$owner" != "$uid" ]; then
+        log "WARN" "--config file is not owned by current user (uid=$uid, owner=$owner)"
+    fi
+
+    return 0
+}
+
+# Stage the auth config into a dedicated read-only 9p share. Must be called
+# AFTER $TEMP_DIR exists and AFTER hypervisor backend functions are sourced.
+# Sets $AUTH_SHARE_DIR and appends to $HV_OPTS / $KERNEL_APPEND.
+setup_auth_share() {
+    [ -z "$AUTH_CONFIG" ] && return 0
+
+    if ! validate_auth_config "$AUTH_CONFIG"; then
+        log "ERROR" "Refusing to stage $AUTH_CONFIG — see above."
+        exit 1
+    fi
+
+    AUTH_SHARE_DIR="$TEMP_DIR/auth_share"
+    # 0700 so nothing outside our process can peek at the staged file.
+    mkdir -p "$AUTH_SHARE_DIR"
+    chmod 700 "$AUTH_SHARE_DIR"
+
+    # Always stage as config.json regardless of source filename — the guest
+    # init script knows to look for this fixed name.
+    if ! cp "$AUTH_CONFIG" "$AUTH_SHARE_DIR/config.json"; then
+        log "ERROR" "Failed to stage auth config"
+        exit 1
+    fi
+    chmod 400 "$AUTH_SHARE_DIR/config.json"
+
+    local auth_tag="${TOOL_NAME}_auth"
+    hv_build_9p_opts "$AUTH_SHARE_DIR" "$auth_tag" "readonly=on"
+    KERNEL_APPEND="$KERNEL_APPEND ${CMDLINE_PREFIX}_auth=1"
+
+    # Deliberately log the *fact* of staging, not the path contents or
+    # credentials. The path itself is useful for debugging and appears in
+    # --verbose mode only.
+    log "INFO" "Registry auth config staged on read-only 9p share (tag=$auth_tag)"
+    log "DEBUG" "Auth source: $AUTH_CONFIG"
+}
+
 cleanup() {
     if [ "$KEEP_TEMP" = "true" ]; then
         log "DEBUG" "Keeping temp directory: $TEMP_DIR"
@@ -956,11 +1144,15 @@ if [ "$BATCH_IMPORT" = "true" ]; then
         fi
     done
 
-    # Add final images command to show what was imported
+    # Show what was imported (informational only).
+    # IMPORTANT: Must not use 'exit' — the command runs inside PID 1 init's
+    # eval, and exit kills init → kernel panic. The import chain runs in a
+    # subshell so its exit code is captured without risk. The images listing
+    # is best-effort and doesn't affect the result.
     if [ "$RUNTIME" = "docker" ]; then
-        COMPOUND_CMD="$COMPOUND_CMD && docker images"
+        COMPOUND_CMD="( $COMPOUND_CMD ); docker images 2>/dev/null; true"
     else
-        COMPOUND_CMD="$COMPOUND_CMD && podman images"
+        COMPOUND_CMD="( $COMPOUND_CMD ); podman images 2>/dev/null; true"
     fi
 
     log "DEBUG" "Batch command: $COMPOUND_CMD"
@@ -1306,6 +1498,10 @@ if [ "$DAEMON_MODE" = "start" ]; then
         log "DEBUG" "CA certificate copied to shared folder"
     fi
 
+    # Stage registry auth config (config.json / auth.json) on a dedicated
+    # read-only 9p share. See setup_auth_share() for the security model.
+    setup_auth_share
+
     log "INFO" "Starting daemon..."
     log "DEBUG" "PID file: $DAEMON_PID_FILE"
     log "DEBUG" "Socket: $DAEMON_SOCKET"
@@ -1361,7 +1557,18 @@ if [ "$DAEMON_MODE" = "start" ]; then
         # Set up port forwards via backend (e.g., iptables for Xen)
         hv_setup_port_forwards
 
-        # Start host-side idle watchdog if timeout is set
+        # Start host-side idle watchdog if timeout is set.
+        #
+        # The watchdog is a long-running background subshell that outlives
+        # vrunner.sh itself. It MUST fully detach from the invoking shell's
+        # stdio: when the caller (e.g. the vdkr CLI, or a test harness that
+        # wraps vdkr in subprocess.run(capture_output=True)) reads
+        # stdout/stderr via pipes, any inherited write-end fd in the
+        # watchdog keeps those pipes open and blocks the caller's
+        # communicate()/read until the daemon is stopped (up to
+        # IDLE_TIMEOUT, default 30 minutes). Redirect all three fds so the
+        # watchdog holds no descriptors from the caller, and disown it so
+        # the shell's job table doesn't retain it either.
         if [ "$IDLE_TIMEOUT" -gt 0 ] 2>/dev/null; then
             ACTIVITY_FILE="$DAEMON_SOCKET_DIR/activity"
             touch "$ACTIVITY_FILE"
@@ -1395,7 +1602,8 @@ if [ "$DAEMON_MODE" = "start" ]; then
                         exit 0
                     fi
                 done
-            ) &
+            ) </dev/null >/dev/null 2>&1 &
+            disown $! 2>/dev/null || true
             log "DEBUG" "Started host-side idle watchdog (timeout: ${IDLE_TIMEOUT}s)"
         fi
 
@@ -1423,6 +1631,11 @@ if [ -n "$CA_CERT" ] && [ -f "$CA_CERT" ]; then
     log "DEBUG" "CA certificate available via 9p"
 fi
 
+# Stage registry auth config (config.json / auth.json) on a dedicated read-only
+# 9p share for non-daemon and batch-import modes. Safe to call when AUTH_CONFIG
+# is empty — it no-ops. See setup_auth_share() for the security model.
+setup_auth_share
+
 log "INFO" "Starting VM ($VCONTAINER_HYPERVISOR)..."
 
 # Interactive mode runs VM in foreground with stdio connected
diff --git a/recipes-containers/vcontainer/vcontainer-initramfs-create.inc b/recipes-containers/vcontainer/vcontainer-initramfs-create.inc
index 3e22bdb1..68011abc 100644
--- a/recipes-containers/vcontainer/vcontainer-initramfs-create.inc
+++ b/recipes-containers/vcontainer/vcontainer-initramfs-create.inc
@@ -44,12 +44,6 @@ python () {
         d.setVarFlag('do_compile', 'nostamp', '1')
         d.setVarFlag('do_deploy', 'nostamp', '1')
 
-    # Conditionally set mcdepends when our multiconfig is configured
-    # (avoids parse errors when BBMULTICONFIG is not set, e.g. yocto-check-layer)
-    mc = d.getVar('VCONTAINER_MULTICONFIG')
-    bbmulticonfig = (d.getVar('BBMULTICONFIG') or "").split()
-    if mc in bbmulticonfig:
-        d.setVarFlag('do_compile', 'mcdepends', 'mc:%s::virtual/kernel:do_deploy' % mc)
 }
 
 # Only populate native sysroot, skip target sysroot to avoid libgcc conflicts
@@ -58,12 +52,17 @@ INHIBIT_DEFAULT_DEPS = "1"
 # Dependencies:
 # 1. The tiny initramfs image (produces cpio.gz)
 # 2. The multiconfig rootfs image (produces squashfs)
-# 3. The kernel from main build
+# 3. The kernel (deployed transitively via image.bbclass do_build)
 #
-# Both initramfs and rootfs images are in the same multiconfig
-do_compile[depends] = "${VCONTAINER_RUNTIME}-tiny-initramfs-image:do_image_complete"
-do_compile[depends] += "${VCONTAINER_RUNTIME}-rootfs-image:do_image_complete"
-# mcdepends set conditionally in anonymous python below
+# Both image recipes inherit core-image/image.bbclass which has:
+#   do_build[depends] += "virtual/kernel:do_deploy"
+# By depending on do_build (not do_image_complete), we ensure the
+# kernel is deployed to MC_DEPLOY before do_compile copies it.
+# Using do_image_complete cut the chain short — it runs before
+# do_build, so virtual/kernel:do_deploy was not guaranteed to have
+# run, causing missing kernel on sstate-accelerated builds.
+do_compile[depends] = "${VCONTAINER_RUNTIME}-tiny-initramfs-image:do_build"
+do_compile[depends] += "${VCONTAINER_RUNTIME}-rootfs-image:do_build"
 
 S = "${UNPACKDIR}"
 B = "${WORKDIR}/build"
@@ -141,14 +140,18 @@ do_compile() {
     # =========================================================================
     # PART 3: COPY KERNEL
     # =========================================================================
+    # Use the multiconfig's deploy directory (same as initramfs/rootfs),
+    # not DEPLOY_DIR_IMAGE which may point to the main config's deploy
+    # directory. The kernel is built as a dependency of the rootfs image
+    # within the same multiconfig.
     bbnote "Copying kernel image..."
-    KERNEL_FILE="${DEPLOY_DIR_IMAGE}/${KERNEL_IMAGETYPE_INITRAMFS}"
+    KERNEL_FILE="${MC_DEPLOY}/${KERNEL_IMAGETYPE_INITRAMFS}"
     if [ -f "${KERNEL_FILE}" ]; then
         cp "${KERNEL_FILE}" ${B}/kernel
         KERNEL_SIZE=$(stat -c%s ${B}/kernel)
         bbnote "Kernel copied: ${KERNEL_SIZE} bytes ($(expr ${KERNEL_SIZE} / 1024 / 1024)MB)"
     else
-        bbwarn "Kernel not found at ${KERNEL_FILE}"
+        bbwarn "Kernel not found at ${KERNEL_FILE} — check that the vruntime multiconfig kernel is built"
     fi
 }
 
diff --git a/recipes-containers/vcontainer/vcontainer-tarball.bb b/recipes-containers/vcontainer/vcontainer-tarball.bb
index ee3c1147..f943cfd0 100644
--- a/recipes-containers/vcontainer/vcontainer-tarball.bb
+++ b/recipes-containers/vcontainer/vcontainer-tarball.bb
@@ -50,6 +50,15 @@ TOOLCHAIN_TARGET_TASK = ""
 TARGET_ARCH = "none"
 TARGET_OS = "none"
 
+# Must use ${SDK_ARCH}-${SDKPKGSUFFIX} (e.g. x86_64-nativesdk) to match
+# the pattern explicitly listed in SSTATE_ARCHS, which SPDX's find_jsonld()
+# searches when locating the static recipe SPDX document generated by
+# do_create_recipe_spdx.  Using ${SDK_ARCH}_${SDK_OS} (x86_64_linux) is NOT
+# in SSTATE_ARCHS and causes do_create_spdx to fatal with "Could not find a
+# static SPDX document named static-vcontainer-tarball".
+# See: meta/classes-global/sstate.bbclass SSTATE_ARCHS definition and
+#      buildtools-tarball.bb for the reference pattern.
+
 # Host tools to include via SDK
 # Note: nativesdk-qemu-vcontainer is a minimal QEMU without OpenGL/virgl
 # to avoid mesa -> llvm -> clang build dependency chain
@@ -66,7 +75,7 @@ SDK_TITLE = "vcontainer tools (vdkr/vpdmn)"
 
 # SDK configuration (same pattern as buildtools-tarball)
 MULTIMACH_TARGET_SYS = "${SDK_ARCH}-nativesdk${SDK_VENDOR}-${SDK_OS}"
-PACKAGE_ARCH = "${SDK_ARCH}_${SDK_OS}"
+PACKAGE_ARCH = "${SDK_ARCH}-${SDKPKGSUFFIX}"
 PACKAGE_ARCHS = ""
 SDK_PACKAGE_ARCHS += "vcontainer-dummy-${SDKPKGSUFFIX}"
 
@@ -131,6 +140,25 @@ VCONTAINER_ARCHITECTURES ?= "x86_64 aarch64"
 
 # Conditionally set mcdepends based on available multiconfigs
 # (avoids parse errors when BBMULTICONFIG is not set, e.g. yocto-check-layer)
+#
+# Two layers of dependency per arch:
+#
+#   1. initramfs-create:do_deploy
+#      Task ordering — guarantees the rootfs.img / kernel / initramfs are
+#      staged under tmp-<mc>/deploy/images/<machine>/<tool>/<arch>/ before
+#      do_populate_sdk reads them.
+#
+#   2. rootfs-image:do_image_complete
+#      Defence-in-depth for sstate consistency. Without this, a rootfs
+#      content change (e.g. adding netavark, switching iptables -> nftables)
+#      would only invalidate the tarball's sstate hash if it propagates
+#      cleanly through rootfs-image:do_build -> initramfs-create:do_compile
+#      -> initramfs-create:do_deploy -> mcdepends. Any break in that chain
+#      (the DEPLOY_DIR-input sstate pattern is one known way to get a stale
+#      hit) re-introduces the netavark-stale-tarball failure mode. Listing
+#      the rootfs-image task directly puts its hash in our chain regardless
+#      of intermediate propagation, and costs nothing if the chain was
+#      already healthy.
 python () {
     bbmulticonfig = (d.getVar('BBMULTICONFIG') or "").split()
     mcdeps = []
@@ -138,6 +166,8 @@ python () {
         if mc in bbmulticonfig:
             mcdeps.append('mc::%s:vdkr-initramfs-create:do_deploy' % mc)
             mcdeps.append('mc::%s:vpdmn-initramfs-create:do_deploy' % mc)
+            mcdeps.append('mc::%s:vdkr-rootfs-image:do_image_complete' % mc)
+            mcdeps.append('mc::%s:vpdmn-rootfs-image:do_image_complete' % mc)
     if mcdeps:
         d.setVarFlag('do_populate_sdk', 'mcdepends', ' '.join(mcdeps))
 
@@ -307,8 +337,9 @@ Quick Start:
 Architectures included: ${ARCHITECTURES}
 
 Contents:
-  init-env.sh           - Environment setup script
-  vdkr, vdkr-<arch>     - Docker CLI wrapper
+  init-env.sh               - Environment setup script (interactive bash)
+  environment-setup-ci      - CI environment (for yocto-autobuilder-helper)
+  vdkr, vdkr-<arch>        - Docker CLI wrapper
   vpdmn, vpdmn-<arch>   - Podman CLI wrapper
   vrunner.sh            - Shared QEMU runner
   vcontainer-common.sh  - Shared CLI code
@@ -399,6 +430,32 @@ ENVEOF
     # Create init-env.sh symlink for convenience
     ln -sf environment-setup-${REAL_MULTIMACH_TARGET_SYS} ${SDK_OUTPUT}/${SDKPATH}/init-env.sh
 
+    # -----------------------------------------------------------------------
+    # CI/AutoBuilder environment script
+    # -----------------------------------------------------------------------
+    # yocto-autobuilder-helper's enable_tools_tarball() parses environment
+    # scripts line-by-line in Python.  It only honours lines starting with
+    # "export " at column 0, only substitutes $PATH, and treats "unset " at
+    # column 0 as a removal.  It does NOT evaluate shell expressions like
+    # $(...) or variable references like $FOO.
+    #
+    # Rather than adding conditional logic to the interactive bash script,
+    # generate a separate flat file with baked-in absolute paths that the
+    # AB parser can consume directly.  SDK relocation rewrites these paths
+    # at install time just like the primary environment-setup-* script.
+    ci_script=${SDK_OUTPUT}/${SDKPATH}/environment-setup-ci
+    cat > $ci_script <<CISCRIPT
+# vcontainer CI environment — for yocto-autobuilder-helper
+# Flat export lines with absolute paths; no shell logic.
+# SDK relocation rewrites these paths at install time.
+export VCONTAINER_DIR="${SDKPATH}"
+export OECORE_NATIVE_SYSROOT="${SDKPATHNATIVE}"
+export PATH="${SDKPATH}:${SDKPATHNATIVE}/usr/bin:/usr/bin:/bin:\$PATH"
+# Clean up - unset to avoid confusing other Yocto tools' >> $script
+unset OECORE_NATIVE_SYSROOT
+CISCRIPT
+    chmod 755 $ci_script
+
     # Create version file
     echo "vcontainer SDK version: ${PV}" > ${SDK_OUTPUT}/${SDKPATH}/version.txt
     echo "Built: $(date)" >> ${SDK_OUTPUT}/${SDKPATH}/version.txt
diff --git a/recipes-containers/vcontainer/vdkr-rootfs-image.bb b/recipes-containers/vcontainer/vdkr-rootfs-image.bb
index e2921ec7..fb5a3718 100644
--- a/recipes-containers/vcontainer/vdkr-rootfs-image.bb
+++ b/recipes-containers/vcontainer/vdkr-rootfs-image.bb
@@ -47,6 +47,8 @@ inherit core-image
 # We need Docker and container tools
 # Note: runc is explicitly listed because vruntime distro sets
 # VIRTUAL-RUNTIME_container_runtime="" to avoid runc/crun conflicts.
+# Note: skopeo is required inside the guest for batch import
+# (skopeo copy oci:... containers-storage:...).
 IMAGE_INSTALL = " \
     packagegroup-core-boot \
     docker-moby \
@@ -58,6 +60,7 @@ IMAGE_INSTALL = " \
     iptables \
     util-linux \
     kernel-modules \
+    ca-certificates \
 "
 
 # No extra features needed
diff --git a/recipes-containers/vcontainer/vpdmn-rootfs-image.bb b/recipes-containers/vcontainer/vpdmn-rootfs-image.bb
index 8808e6b2..909e1298 100644
--- a/recipes-containers/vcontainer/vpdmn-rootfs-image.bb
+++ b/recipes-containers/vcontainer/vpdmn-rootfs-image.bb
@@ -42,6 +42,8 @@ inherit core-image
 # Podman is daemonless - no containerd required!
 # Note: crun is explicitly listed because vruntime distro sets
 # VIRTUAL-RUNTIME_container_runtime="" to avoid runc/crun conflicts.
+# Note: skopeo is required inside the guest for batch import
+# (skopeo copy oci:... containers-storage:...).
 IMAGE_INSTALL = " \
     packagegroup-core-boot \
     podman \
@@ -52,7 +54,7 @@ IMAGE_INSTALL = " \
     aardvark-dns \
     busybox \
     iproute2 \
-    iptables \
+    nftables \
     util-linux \
     ca-certificates \
 "
@@ -121,12 +123,22 @@ EOF
 
     # Create containers.conf for podman engine settings
     cat > ${IMAGE_ROOTFS}/etc/containers/containers.conf << 'EOF'
-[engine]
-# Location of helper binaries (netavark, aardvark-dns)
-helper_binaries_dir = ["/usr/libexec/podman"]
-
 [network]
-# Use netavark as the network backend
 network_backend = "netavark"
 EOF
+
+    # Prevent libnss_systemd segfaults — systemd is not running in the
+    # vruntime VM (busybox init), but libnss_systemd.so is installed as
+    # a dependency. Override nsswitch.conf to use only files/compat.
+    cat > ${IMAGE_ROOTFS}/etc/nsswitch.conf << 'EOF'
+passwd:     files
+group:      files
+shadow:     files
+hosts:      files dns
+networks:   files
+protocols:  files
+services:   files
+ethers:     files
+rpc:        files
+EOF
 }