feat: nested sandbox support (sandbox-in-sandbox)

Allow running
╭───── VM Created ──────╮
│ Created VM 'sbx-ohm'. │
╰───────────────────────╯
             VM Details
┌─────────┬─────────────────────────┐
│ Name    │ sbx-ohm                 │
│ Status  │ running                 │
│ OS      │ ubuntu                  │
│ Started │ 2026-06-26 17:17:51 UTC │
└─────────┴─────────────────────────┘
Next: smolvm sandbox shell sbx-ohm
SSH:  smolvm sandbox ssh sbx-ohm
Info: smolvm sandbox info sbx-ohm inside a SmolVM sandbox guest.

Changes:
- backends.py: add _running_inside_smolvm_guest() that detects nested
  context via SMOLVM_NESTED env var or /run/smolvm-guest marker file;
  auto-selects QEMU backend when nested instead of Firecracker
- qemu_args.py: force TCG accelerator when running inside a guest
  (no KVM available); reads SMOLVM_QEMU_ACCEL env var first so it
  can still be overridden explicitly
- comm/select.py: disable vsock when nested (no /dev/vhost-vsock in
  guest); falls back to SSH for the control channel
- cloud_init.py: write nested env vars to /etc/environment (not just
  profile.d), add /etc/pip.conf, write /run/smolvm-guest in bootcmd,
  install arch-aware qemu-system package in runcmd
- Dockerfile.base-rootfs: bake python3-pip, python3-venv, qemu-utils,
  qemu-system-arm/x86 (arch-detected), nftables into the base image
- preset-init.sh: write /run/smolvm-guest marker and /etc/pip.conf
  at PID 1 startup on every boot
- tests/test_qemu_args.py: patch _KVM_DEV and _SMOLVM_GUEST_MARKER
  in autouse fixture so Linux host simulation works from macOS runner

After image rebuild and new release, the user flow becomes:
  smolvm sandbox create --name my-computer --memory 2048
  smolvm sandbox ssh my-computer
  pip install smolvm
  smolvm sandbox create --name inner --os ubuntu --memory 512 --boot-timeout 300

Author: SauravMishraaa

scripts/ci/Dockerfile.base-rootfs

@@ -30,6 +30,15 @@ RUN apt-get update -qq \
         git \
         bash \
         python3 \
+        python3-pip \
+        python3-venv \
+        qemu-utils \
+        nftables \
+    && ARCH="$(dpkg --print-architecture)" \
+    && case "$ARCH" in \
+         amd64) apt-get install -y -qq --no-install-recommends qemu-system-x86 ;; \
+         arm64) apt-get install -y -qq --no-install-recommends qemu-system-arm ;; \
+       esac \
     && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y -qq --no-install-recommends nodejs \
     && apt-get purge -y -qq gnupg \

scripts/ci/preset-init.sh

@@ -82,6 +82,34 @@ chmod 1777 /tmp
 
 log_ts "root-ready"
 
+# ── Nested SmolVM guest identity ─────────────────────────────
+# Mark this as a SmolVM guest so nested smolvm invocations auto-select
+# QEMU+TCG instead of Firecracker, and skip vsock (no /dev/vhost-vsock).
+# Written to /run (tmpfs) so it's always present after boot regardless of
+# whether the user's shell sources /etc/profile.d or /etc/environment.
+touch /run/smolvm-guest
+
+# ── pip system-wide config ───────────────────────────────────
+# Allow pip to install into the system Python without --break-system-packages.
+# This makes `pip install smolvm` work out of the box inside a sandbox.
+if [ ! -f /etc/pip.conf ]; then
+    printf '[global]\nbreak-system-packages = true\n' > /etc/pip.conf
+fi
+
+# ── Nested SmolVM environment ────────────────────────────────
+# Write key env vars to /etc/environment so they apply to all sessions
+# (SSH non-login, subprocesses, etc.) without requiring profile.d sourcing.
+# These are safe to set on every boot — they're no-ops on a non-nested host.
+if ! grep -q 'SMOLVM_NESTED' /etc/environment 2>/dev/null; then
+    cat >> /etc/environment <<'EOF'
+SMOLVM_NESTED=1
+SMOLVM_BACKEND=qemu
+SMOLVM_QEMU_ACCEL=tcg
+SMOLVM_BOOT_TIMEOUT=300
+PIP_BREAK_SYSTEM_PACKAGES=1
+EOF
+fi
+
 # ── Guest agent (vsock control plane) ────────────────────────
 # Started before networking and sshd, so explicit-vsock sandboxes can become
 # ready without waiting for SSH host-key generation or network setup. SSH-only

src/smolvm/cli/commands/app.py

@@ -918,6 +918,13 @@ def _make_start_callback(preset_name: str, command_name: str) -> Any:
             )
             @click.option("--mount", "mounts", multiple=True, metavar="HOST_PATH[:GUEST_PATH]")
             @click.option("--writable-mounts", is_flag=True)
+            @click.option(
+                "--disk-mode",
+                type=click.Choice(["auto", "isolated", "shared"]),
+                default="auto",
+                show_default=True,
+                help="Disk lifecycle mode (isolated = per-VM disk, shared = direct from source).",
+            )
             @click.option("--install-timeout", type=positive_float_type(), default=600.0)
             @click.option("--attach/--no-attach", default=None)
             @comm_channel_option
@@ -932,6 +939,7 @@ def start(
                 os_name: str | None,
                 mounts: tuple[str, ...],
                 writable_mounts: bool,
+                disk_mode: str,
                 install_timeout: float,
                 attach: bool | None,
                 comm_channel: str | None,
@@ -951,6 +959,7 @@ def start(
                         os=os_name,
                         mounts=_mounts(mounts),
                         writable_mounts=writable_mounts,
+                        disk_mode=disk_mode,
                         install_timeout=install_timeout,
                         attach=attach,
                         comm_channel=comm_channel,

src/smolvm/cli/commands/options.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import platform
 from collections.abc import Callable, Mapping
 from functools import wraps
@@ -85,7 +86,7 @@ def boot_timeout_option(fn: F) -> F:
         "--boot-timeout",
         type=float,
         callback=_positive_number,
-        default=30.0,
+        default=_boot_timeout_default(),
         show_default=True,
         help="Seconds to wait for the sandbox to be ready.",
     )(fn)
@@ -107,3 +108,13 @@ def positive_int_type() -> click.IntRange:
 
 def positive_float_type() -> click.FloatRange:
     return click.FloatRange(min=0, min_open=True)
+
+
+def _boot_timeout_default() -> float:
+    raw = os.environ.get("SMOLVM_BOOT_TIMEOUT", "").strip()
+    if not raw:
+        return 30.0
+    try:
+        return float(raw)
+    except ValueError:
+        return 30.0

src/smolvm/comm/select.py

@@ -38,7 +38,7 @@
 
 from smolvm.comm.base import CommChannelKind
 from smolvm.exceptions import SmolVMError
-from smolvm.runtime.backends import BACKEND_FIRECRACKER, BACKEND_QEMU
+from smolvm.runtime.backends import BACKEND_FIRECRACKER, BACKEND_QEMU, _running_inside_smolvm_guest
 from smolvm.types import GuestOS
 
 _VHOST_VSOCK_DEV = Path("/dev/vhost-vsock")
@@ -49,7 +49,13 @@ def host_supports_vsock() -> bool:
 
     True only on Linux with the ``vhost_vsock`` driver loaded (its device node
     present). macOS/HVF has no equivalent, so this returns False there.
+
+    Also returns False inside a nested SmolVM sandbox: the guest kernel exposes
+    no ``/dev/vhost-vsock`` in that context, and the sandbox always uses SSH as
+    its control channel.
     """
+    if _running_inside_smolvm_guest():
+        return False
     return platform.system() == "Linux" and _VHOST_VSOCK_DEV.exists()
 
 

src/smolvm/facade.py

@@ -79,6 +79,7 @@
     BACKEND_FIRECRACKER,
     BACKEND_LIBKRUN,
     BACKEND_QEMU,
+    _running_inside_smolvm_guest,
     resolve_backend,
 )
 from smolvm.runtime.boot_profiles import (
@@ -575,6 +576,11 @@ def _build_auto_config(
     public_key_value = public_key_path.read_text().strip()
 
     resolved_memory = _AUTO_CONFIG_DEFAULT_MEM_SIZE_MIB[resolved_os]
+    # Inside a nested SmolVM guest, TCG (software emulation) is used because
+    # KVM is unavailable. Use a smaller default so the inner VM fits within
+    # the outer sandbox's memory without the user needing to specify --memory.
+    if memory is None and _running_inside_smolvm_guest():
+        resolved_memory = min(resolved_memory, 512)
     if memory is not None:
         resolved_memory = memory
     default_disk_size_mib = _AUTO_CONFIG_DEFAULT_DISK_SIZE_MIB[resolved_os]

src/smolvm/images/builder.py

@@ -559,7 +559,9 @@ def build_alpine_ssh(
     iproute2 \\
     curl \\
     bash \\
-    python3
+    python3 \\
+    qemu-img \\
+    qeum-system-x86_64
 
 # Configure SSH. Host keys are generated at first boot in /init, not here,
 # so each VM gets a unique SSH identity — required for safely sharing images.

src/smolvm/images/cloud_init.py

@@ -37,8 +37,17 @@ def default_user_data(ssh_public_key: str) -> str:
     shell: /bin/bash
     ssh_authorized_keys:
       - {ssh_public_key}
+package_update: true
+packages:
+  - python3-pip
+  - python3-venv
+  - qemu-utils
+  - openssh-client
+  - iproute2
+  - nftables
 bootcmd:
   - mkdir -p /etc/systemd/resolved.conf.d
+  - touch /run/smolvm-guest
   - ['sh', '-c', '{dns_cmd}']
   - ['systemctl', 'restart', 'systemd-resolved']
   - ['systemctl', 'restart', 'systemd-timesyncd']
@@ -53,8 +62,36 @@ def default_user_data(ssh_public_key: str) -> str:
     content: |
       #!/bin/sh
       printf '\\n  SmolVM Sandbox — powered by Celesto AI\\n  https://celesto.ai\\n\\n'
+  - path: /etc/pip.conf
+    permissions: "0644"
+    content: |
+      [global]
+      break-system-packages = true
+  - path: /etc/environment
+    permissions: "0644"
+    append: true
+    content: |
+      SMOLVM_NESTED=1
+      SMOLVM_BACKEND=qemu
+      SMOLVM_QEMU_ACCEL=tcg
+      SMOLVM_BOOT_TIMEOUT=300
+      PIP_BREAK_SYSTEM_PACKAGES=1
+  - path: /etc/profile.d/smolvm_nested.sh
+    permissions: "0644"
+    content: |
+      export SMOLVM_NESTED=1
+      export SMOLVM_BACKEND=qemu
+      export SMOLVM_QEMU_ACCEL=tcg
+      export SMOLVM_BOOT_TIMEOUT=300
+      export PIP_BREAK_SYSTEM_PACKAGES=1
 runcmd:
   - rm -f /etc/update-motd.d/10-help-text /etc/update-motd.d/60-unminimize
+  - ['sh', '-lc', 'command -v pip >/dev/null || ln -sf /usr/bin/pip3 /usr/local/bin/pip']
+  - >
+    case "$(uname -m)" in
+      aarch64|arm64) apt-get install -y --no-install-recommends qemu-system-arm ;;
+      x86_64|amd64)  apt-get install -y --no-install-recommends qemu-system-x86 ;;
+    esac
   - >
     systemctl restart ssh || systemctl restart sshd ||
     service ssh restart || service sshd restart || true

src/smolvm/runtime/backends.py

@@ -18,6 +18,7 @@
 
 import os
 import platform
+from pathlib import Path
 
 from smolvm.utils import which  # noqa: F401 — imported for test patching
 
@@ -28,6 +29,22 @@
 
 SUPPORTED_BACKENDS = {BACKEND_FIRECRACKER, BACKEND_QEMU, BACKEND_LIBKRUN}
 
+# Marker file written by cloud-init inside every SmolVM guest image.
+# Presence means we're running inside a SmolVM sandbox, not on the host.
+_SMOLVM_GUEST_MARKER = Path("/run/smolvm-guest")
+
+
+def _running_inside_smolvm_guest() -> bool:
+    """Return True if this process is running inside a SmolVM sandbox guest.
+
+    Checks (in order):
+    1. ``SMOLVM_NESTED=1`` environment variable (set by profile.d / /etc/environment).
+    2. The ``/run/smolvm-guest`` marker file written by cloud-init at boot.
+    """
+    if os.environ.get("SMOLVM_NESTED") == "1":
+        return True
+    return _SMOLVM_GUEST_MARKER.exists()
+
 
 def resolve_backend(requested: str | None = None) -> str:
     """Resolve the effective backend name.
@@ -52,6 +69,8 @@ def resolve_backend(requested: str | None = None) -> str:
         system = platform.system().lower()
         if system == "darwin":
             return BACKEND_QEMU
+        if _running_inside_smolvm_guest():
+            return BACKEND_QEMU
         return BACKEND_FIRECRACKER
 
     if raw in SUPPORTED_BACKENDS:

src/smolvm/runtime/qemu_args.py

@@ -35,6 +35,7 @@
 from typing import cast
 
 from smolvm.exceptions import SmolVMError
+from smolvm.runtime.backends import _running_inside_smolvm_guest
 from smolvm.runtime.guest_platforms import GuestPlatformSpec
 from smolvm.runtime.qemu import QEMU_ROOT_NODE_NAME
 from smolvm.types import GuestOS, QemuMachine, VMInfo
@@ -50,9 +51,10 @@
 _Q35_AHCI_PORTS = 6
 
 _QEMU_MACHINE_ENV = "SMOLVM_QEMU_MACHINE"
-_QEMU_MICROVM_MACHINE = "microvm,accel=kvm,acpi=on,pcie=off,pic=off,pit=off,rtc=on"
+_QEMU_MICROVM_MACHINE_BASE = "microvm,acpi=on,pcie=off,pic=off,pit=off,rtc=on"
 _QEMU_MACHINE_VALUES: set[QemuMachine] = {"auto", "q35", "microvm"}
-
+_QEMU_ACCEL_ENV = "SMOLVM_QEMU_ACCEL"
+_KVM_DEV = Path("/dev/kvm")
 
 # Candidate UEFI firmware locations for aarch64 QEMU firmware-boot.
 # Searched in order; the first existing file wins. macOS Homebrew ships
@@ -68,6 +70,28 @@
 )
 
 
+def _resolve_qemu_accel(host_system: str) -> tuple[str, str]:
+    """Return (accel, cpu) for QEMU based on host + env."""
+    raw = os.environ.get(_QEMU_ACCEL_ENV, "").strip().lower()
+    if raw in {"kvm", "hvf", "tcg"}:
+        accel = raw
+    else:
+        # Inside a SmolVM guest there is no KVM or HVF — always use TCG.
+        # We only apply this guard when the effective host_system is Linux
+        # (i.e. not when tests override host_system to exercise Linux code
+        # paths from a Darwin test runner).
+        if host_system == "Linux" and _running_inside_smolvm_guest():
+            accel = "tcg"
+        elif host_system == "Darwin":
+            accel = "hvf"
+        else:
+            accel = "kvm" if _KVM_DEV.exists() and os.access(_KVM_DEV, os.R_OK | os.W_OK) else "tcg"
+
+    # TCG needs a generic CPU model; "host" is only valid for KVM/HVF.
+    cpu = "host" if accel in {"kvm", "hvf"} else "max"
+    return accel, cpu
+
+
 def _find_aarch64_uefi_firmware() -> Path | None:
     """Return the first existing aarch64 UEFI firmware file, or ``None``."""
     for candidate in _AARCH64_EDK2_FIRMWARE_CANDIDATES:
@@ -337,10 +361,12 @@ def build_qemu_argv(
         # macOS → Hypervisor.framework; Linux → KVM (if /dev/kvm is
         # missing the user couldn't run firecracker either, so requiring
         # KVM here is consistent).
-        if system == "Darwin":
-            machine, cpu = "virt,accel=hvf", "host"
-        else:
-            machine, cpu = "virt,accel=kvm", "host"
+        # if system == "Darwin":
+        #     machine, cpu = "virt,accel=hvf", "host"
+        # else:
+        #     machine, cpu = "virt,accel=kvm", "host"
+        accel, cpu = _resolve_qemu_accel(system)
+        machine = f"virt,accel={accel}"
         cmd.extend(["-machine", machine, "-cpu", cpu])
         if vm_info.config.boot_mode == "firmware":
             firmware_path = _find_aarch64_uefi_firmware()
@@ -373,7 +399,9 @@ def build_qemu_argv(
             ]
         )
     elif use_qemu_microvm:
-        cmd.extend(["-machine", _QEMU_MICROVM_MACHINE, "-cpu", "host"])
+        accel, cpu = _resolve_qemu_accel(system)
+        machine = f"microvm,accel={accel},{_QEMU_MICROVM_MACHINE_BASE.split(',', 1)[1]}"
+        cmd.extend(["-machine", machine, "-cpu", cpu])
         for drive_id in extra_drive_ids:
             cmd.extend(["-device", f"virtio-blk-device,drive={drive_id}"])
         for fsdev_id, tag in workspace_fsdev_ids:
@@ -390,10 +418,12 @@ def build_qemu_argv(
         # See accel comment on the aarch64 branch above. Without
         # accel=kvm on Linux, QEMU runs TCG and Ubuntu cloud-init blows
         # past wait_for_ssh in seconds vs minutes.
-        if system == "Darwin":
-            machine_base, cpu_base = "q35,accel=hvf", "host"
-        else:
-            machine_base, cpu_base = "q35,accel=kvm", "host"
+        # if system == "Darwin":
+        #     machine_base, cpu_base = "q35,accel=hvf", "host"
+        # else:
+        #     machine_base, cpu_base = "q35,accel=kvm", "host"
+        accel, cpu = _resolve_qemu_accel(system)
+        machine_base, cpu_base = f"q35,accel={accel}", cpu
         # Per-OS extras are comma-appended to the base. For _LINUX_SPEC
         # both extra tuples are empty → byte-identical to the legacy form.
         machine_str = ",".join((machine_base, *platform_spec.machine_extra_opts))