pi-microsandbox 0.1.1 → 0.2.0

package/README.md

@@ -39,8 +39,11 @@ Keep your everyday defaults in global config and project-specific settings in
 variables and session overrides let you adjust a particular run without
 rewriting the project's setup.
 
-The agent gets an environment built for the job. You don't have to make the
-same decisions every time you start it.
+The agent gets an environment built for the job. Image cohorts built from this
+version include Docker Engine 29.8.0, Buildx 0.37.1, and Compose 5.5.1. The
+daemon and its containers run inside the microVM; pi-microsandbox never connects them to the
+host Docker socket. You don't have to make the same decisions every time you
+start it.
 
 [Configure your project's sandbox →](docs/configuration.md)
 
@@ -50,26 +53,25 @@ You'll need Pi, **Node.js 22.19.0+**, and one of the supported host targets:
 Apple Silicon macOS (`darwin-arm64`), GNU Linux x86_64
 (`linux-x64-gnu`), or GNU Linux arm64 (`linux-arm64-gnu`). Live sandboxes also
 need host virtualization support. The POSIX lock addon is bundled and installs
-without lifecycle scripts or a compiler; keep npm optional dependencies enabled
-for the Microsandbox platform package.
+without lifecycle scripts or a compiler.
 [Full requirements and installation help →](docs/getting-started.md)
 
-Install the Microsandbox CLI first:
+Install pi-microsandbox:
 
 ```sh
-curl -fsSL https://install.microsandbox.dev | sh
+pi install npm:pi-microsandbox
 ```
 
-For alternate installation methods and any Microsandbox-specific setup,
-runtime, or troubleshooting details, use the official
-[Microsandbox documentation](https://docs.microsandbox.dev/). The documentation
-in this repository covers the Pi integration.
-
-Then install pi-microsandbox:
+That command also installs the pinned Microsandbox SDK, CLI, and matching
+platform runtime. A separate Microsandbox installation is not required on a
+supported host. Keep npm optional dependencies enabled so npm installs the
+platform package.
 
-```sh
-pi install npm:pi-microsandbox
-```
+If the platform package is unavailable, you can provide a standalone `msb`
+binary with `MSB_PATH`. See the official
+[Microsandbox documentation](https://docs.microsandbox.dev/) for standalone
+installation and runtime troubleshooting. The documentation in this repository
+covers the Pi integration.
 
 From a Git repository, start Pi with its own isolated workspace:
 

package/docs/commands.md

@@ -23,8 +23,9 @@ The extension registers `/msb`:
 /msb help
 ```
 
-`/msb status` reports the full sandbox name, mode, image, PID, age, branch/SHA,
-and retained volume metadata when available. Six-character IDs in UI text are
+`/msb status` reports the full sandbox name, mode, image, PID, age, Docker
+mode/readiness/version/storage driver, branch/SHA, and retained volume metadata
+when available. Six-character IDs in UI text are
 display abbreviations only. `/msb prune` walks all SDK list pages and reports
 removed, kept, and error entries; **volumes are never pruned**.
 

package/docs/configuration.md

@@ -15,9 +15,11 @@ The following is a small project example:
 ```toml
 # .pi-msb.toml
 mode = "git"
-image = "ghcr.io/hcohe/pi-microsandbox:1.0.0@sha256:00ea1e0911189815614e8a8eee36d1fd64f0f1edb39492e0bda9f273c834e59f"
+image = "ghcr.io/hcohe/pi-microsandbox:1.1.0@sha256:ab4e99d4232f827b3f295ff3210437e01446dbb672ef0d0c78358566170ac86c"
 pull_policy = "if-missing"
 bootstrap_tools = "auto"
+cpus = 4
+memory_mib = 8192
 idle_timeout_sec = 600
 fallback_mode = "block"
 show_footer = true # Default; set false to hide the MSB footer status.
@@ -26,6 +28,10 @@ show_footer = true # Default; set false to hide the MSB footer status.
 mode = "default" # default | open | allowlist | deny
 allow_dns = true
 
+[docker]
+mode = "auto" # auto | require | disabled
+startup_timeout_ms = 15000
+
 # Project secrets should use references, not literals.
 [[secrets]]
 env = "NPM_TOKEN"
@@ -50,17 +56,40 @@ Important configuration behavior:
   contents, custom image workflows, and the required guest commands.
   `bootstrap_tools = "auto"` probes those commands and uses noninteractive
   `apt-get` under the configured network policy when a custom image is missing
-  them. `false` blocks with the missing command list instead.
+  them. `false` blocks with the missing command list instead. New sandboxes use
+  4 CPUs and 8192 MiB by default; set `cpus` and `memory_mib` lower if the host
+  cannot support that allocation.
+- `docker.mode = "auto"` starts the guest daemon when the image has Docker and
+  reports `missing` for older or custom images without it. `"require"` blocks
+  sandbox preparation if Docker is absent or cannot start. `"disabled"` leaves
+  the installed daemon stopped. `startup_timeout_ms` must be an integer from 1
+  through 300000. Readiness is pinned to the managed guest Unix socket and
+  ignores inherited Docker client endpoint settings. Docker state stays on the
+  disposable guest root filesystem. Small builds should have at least 1 GiB; larger Compose stacks usually need
+  2 GiB or more.
 - `network.mode = "default"` leaves the SDK's default policy in place. `open`
   allows all network traffic, including private/host access; `allowlist` is
   default-deny with configured host/DNS rules; `deny` disables networking.
   Published ports default to loopback unless a bind address is specified.
+  Nested containers remain subject to this outer policy. A Docker `-p` mapping
+  exposes a port only inside the microVM. Host access also needs a matching
+  `network.publish_ports` entry created with the sandbox, for example
+  `publish_ports = ["127.0.0.1:8080:8080"]` together with `docker run -p
+  0.0.0.0:8080:8080 ...`. Docker's random host-port form cannot create that
+  outer mapping.
 - Secrets require a non-empty `allow_hosts` list. `$ENV:NAME` and `$FILE:path`
   references are resolved only while constructing the SDK builder. Effective
-  config, warnings, errors, and `/msb config` redact literal values.
+  config, warnings, errors, and `/msb config` redact literal values. Process
+  control variables such as `DOCKER_HOST`, `DOCKER_CONTEXT`, `PATH`,
+  `BASH_ENV`, and `LD_PRELOAD` cannot be forwarded with `host_env` or injected
+  as secrets.
 - Directory/file mounts have absolute guest paths. Project mounts outside the
   repository must be read-only unless a global/session policy authorizes the
-  write. Mounts may not overlap or shadow the project mount or reserved `/tmp`.
+  write. Mounts may not overlap or shadow the project mount, reserved `/tmp`,
+  protected guest system trees such as `/usr`, `/bin`, `/proc`, and `/sys`, or
+  Docker runtime paths such as `/run`, `/var/run`, and `/var/lib/docker`.
+  Host mount sources are canonicalized before use; socket targets, including
+  Docker sockets reached through symlink aliases, are rejected.
 - The legacy `host_ro_allowlist` is converted to canonical read-only mounts and
   emits a deprecation warning.
 
@@ -71,6 +100,8 @@ PI_MSB_DISABLE=1                 # explicit host/off mode
 PI_MSB_MODE=none                 # nested scalar example
 PI_MSB_PULL_POLICY=always        # recheck mutable custom image tags on creation
 PI_MSB_NETWORK__MODE=deny        # nested environment key
+PI_MSB_DOCKER__MODE=require      # require a working guest Docker daemon
+PI_MSB_DOCKER__STARTUP_TIMEOUT_MS=30000
 PI_MSB_FALLBACK_MODE=host        # opt into automatic host fallback
 PI_MSB_SHOW_FOOTER=false         # hide the MSB status from Pi's footer
 PI_MSB_ROUTE_TOOLS='read,write'  # POSIX delimiter for simple arrays

package/docs/development.md

@@ -23,6 +23,28 @@ npm audit --omit=dev
 The smoke and unit tests do not require KVM, image pulls, or a live sandbox.
 The boot-speed check and live matrix below are explicit VM tests.
 
+To test the current extension and default image together, run:
+
+```sh
+just dev
+```
+
+`dev-flock` builds and smoke-tests the native owner-lock addon for the current
+host. `dev-image` builds the current `default` variant as
+`pi-microsandbox-dev:local` and imports it into Microsandbox's separate image
+cache. `dev` runs both prerequisites, then starts Pi with this checkout's
+extension explicitly loaded alongside your normal discovered extensions. It
+forces the local image with `pull_policy = "never"`, requires Docker, and uses
+4 CPUs and 8192 MiB. Docker caching keeps repeat builds short
+when image inputs have not changed. Pass Pi arguments directly, for example:
+
+```sh
+just dev --continue
+just dev "Run docker info and report the storage driver"
+```
+
+Run `just dev-image` by itself when you only need to refresh the local image.
+
 ### Bundled flock addon
 
 Consumers receive prebuilt lock addons and do not need native build tools. Only
@@ -117,14 +139,20 @@ Without that variable the script prints a `SKIP` line for every scenario and
 exits successfully; this skip path does not validate virtualization. If
 virtualization is unavailable, it prints the reason and skips the matrix rather
 than reporting false failures. Set `PI_MSB_LIVE_IMAGE` to select the main live
-test image; the default is `ghcr.io/hcohe/pi-microsandbox:latest`.
+test image; the default is `ghcr.io/hcohe/pi-microsandbox:latest`. The main
+scenarios use `pull_policy = "always"` by default. To test an image already
+imported with `msb load`, set `PI_MSB_LIVE_PULL_POLICY=never`; do not use that
+override as evidence for a published image.
 The prepared-image scenario boots all six latest variant tags under
 `network.mode = "deny"` with bootstrap disabled. Set
 `PI_MSB_LIVE_PREPARED_IMAGES` to a comma-separated image cohort, or use the
 legacy singular `PI_MSB_LIVE_PREPARED_IMAGE` to test one image. The live matrix
 uses `pull_policy = "always"` intentionally so mutable development tags cannot
-remain stale on the self-hosted runner. Review the output to confirm that all 16 scenarios report
-`PASS`, not `SKIP`.
+remain stale on the self-hosted runner. Review the output to confirm that every scenario reports `PASS`, not `SKIP`.
+Docker release validation must cover daemon readiness, bridge DNS and HTTPS,
+user-defined networking, Buildx, Compose, idle wake, double port publishing,
+and nested-container enforcement for deny and allowlist policies. A skipped
+Docker scenario is not release evidence.
 
 ## Image development
 
@@ -135,7 +163,17 @@ variant's mutable latest tag and a commit-specific tag. Release builds pin the
 Ubuntu image digest and one dated apt snapshot for all variants, while published
 images restore normal apt sources for project use. See [Images](images.md#add-a-language-variant)
 for the modular installer and verifier architecture, contribution rules, and
-local validation commands.
+local validation commands. Docker changes must also pass:
+
+```sh
+node scripts/image-variants.mjs matrix
+shellcheck -e SC1091 default-image/install/*.sh default-image/verify/*.sh
+```
+
+The common image verifier checks Docker Engine 29.8.0, containerd 2.3.4, runc
+1.5.1, Buildx 0.37.1, Compose 5.5.1, and Ubuntu's iptables-nft/nftables tools.
+Docker daemon and nested-container behavior require the live microVM matrix;
+they cannot be validated during a Dockerfile build.
 
 ## Releases
 

package/docs/getting-started.md

@@ -24,12 +24,12 @@ It is loaded lazily when an owner lock is first needed. Consumer installation
 does not compile native code or require Python, a C/C++ toolchain, or npm
 lifecycle scripts; installation with scripts disabled is supported.
 
-Keep optional dependencies enabled. `microsandbox@0.6.16` supplies its matching
-native addon and runtime binaries through an optional platform package. If that
+Keep optional dependencies enabled. `microsandbox@0.6.16` supplies its CLI,
+native addon, and runtime binaries through an optional platform package. If that
 platform package is missing, reinstall with optional dependencies enabled,
 install the matching Microsandbox platform package, or set `MSB_PATH` to a
-working `msb` binary. These alternatives do not remove the host virtualization
-requirement.
+working standalone `msb` binary. These alternatives do not remove the host
+virtualization requirement.
 
 ## Install
 
@@ -39,6 +39,11 @@ Install the package for the current user with Pi:
 pi install npm:pi-microsandbox
 ```
 
+This is the only package installation step on a supported host. The dependency
+includes the Microsandbox SDK and CLI; its matching optional platform package
+includes the host runtime. You do not need to run the standalone Microsandbox
+installer first.
+
 Before starting a sandbox, review [configuration](configuration.md) and choose a
 [published variant or custom image](images.md) if the versioned default image
 does not fit the project.

package/docs/images.md

@@ -15,7 +15,7 @@ Push an exact `image-vVERSION` Git tag to publish a release cohort. Package
 
 | Variant | Contents | Release tag | Latest tag |
 | --- | --- | --- | --- |
-| `base` | Required guest commands and CA certificates, without a language toolchain | `base-VERSION` | `base-latest` |
+| `base` | Required guest commands, CA certificates, Docker 29.8.0, Buildx 0.37.1, and Compose 5.5.1; no language toolchain | `base-VERSION` | `base-latest` |
 | `node` | Base plus Node.js 24.21.0, npm, pnpm 12.3.4, Yarn 1.22.22, and native addon build support | `node-VERSION` | `node-latest` |
 | `python` | Base plus Ubuntu Python 3, pip, uv/uvx 0.12.12, and native extension build support | `python-VERSION` | `python-latest` |
 | `rust` | Base plus Rust 1.98.0, Cargo, rustup, and native dependency build support | `rust-VERSION` | `rust-latest` |
@@ -23,8 +23,12 @@ Push an exact `image-vVERSION` Git tag to publish a release cohort. Package
 | `default` | Base plus the Node.js, Python, Rust, and Go modules above | `VERSION` | `latest` |
 
 The base contract includes `bash`, `sh`, `git`, `rg`, `file`, `cat`, `mkdir`,
-`rm`, and the other core commands used by the image verification scripts. CA
-certificates support HTTPS Git operations.
+`rm`, Docker Engine and CLI 29.8.0, containerd 2.3.4, runc 1.5.1, Buildx
+0.37.1, Compose 5.5.1, and the Ubuntu iptables-nft and nftables tools. CA
+certificates support HTTPS Git operations. Docker is part of the common base
+rather than a language toolchain, so all six variants built from this version
+contain it. The extension's digest-pinned default changes only after that cohort
+has been published and verified.
 
 Select a variant in trusted project configuration:
 
@@ -46,10 +50,10 @@ an updated mutable tag, or `"never"` to require a cached local image.
 [`default-image/variants.json`](../default-image/variants.json) is the single
 source of variant composition and tag names. The workflow passes each entry's
 toolchain list to one generic
-[`default-image/Dockerfile`](../default-image/Dockerfile). Modular
-`default-image/install/<language>.sh` and
-`default-image/verify/<language>.sh` scripts install and exercise each selected
-language.
+[`default-image/Dockerfile`](../default-image/Dockerfile). The common Docker installer runs before the modular
+`default-image/install/<language>.sh` scripts. The corresponding common
+verifier checks Docker and its CLI plugins in every variant; language verifiers
+then exercise each selected toolchain.
 
 The `default` variant runs the same Node.js, Python, Rust, and Go modules as the
 individual variants. It does not have a duplicate package list. This keeps an
@@ -63,7 +67,11 @@ can install current packages at runtime.
 ## Build a custom image
 
 A custom image must provide `bash`, `sh`, `git`, `rg`, `file`, `cat`, `mkdir`,
-and `rm`. Install CA certificates if the guest will use Git over HTTPS. With
+and `rm`. Docker is optional for custom images. The default `docker.mode =
+"auto"` records it as missing and continues; use `docker.mode = "require"` when
+the image contract must include a working daemon. pi-microsandbox does not
+install Docker during sandbox startup. Install CA certificates if the guest
+will use Git over HTTPS. With
 `bootstrap_tools = "auto"`, pi-microsandbox can install missing required
 commands through `apt-get` when the network policy permits it. A prepared image
 is required when bootstrap is disabled or package repositories are unavailable.

package/docs/safety.md

@@ -28,6 +28,23 @@ addon. Unsupported hosts can still load Pi and remain blocked or explicitly
 off. pi-microsandbox supports Apple Silicon macOS and GNU Linux x86_64 or arm64
 with KVM; Windows, Intel macOS, and musl Linux are not supported.
 
+## Docker inside the guest
+
+The Docker daemon runs inside the microVM and listens only on the guest Unix
+socket. Access to that socket is root-equivalent inside the guest, not on the
+host. Readiness probes explicitly select that socket and reject unverified
+socket ownership. Docker and process-control environment variables are cleared
+for preparation, and configuration cannot forward them. Mounts that shadow
+protected guest executables or Docker runtime paths are rejected. The extension never mounts the host Docker
+socket, starts a host daemon, or copies host Docker configuration and registry
+credentials into the guest.
+
+A container can still reach anything already mounted into the microVM. In
+`direct` mode that includes the host project directory; in Git mode it includes
+the retained workspace; explicitly configured mounts are visible too. Treat a
+Dockerfile or Compose file as guest-root code and use read-only mounts where
+possible. Container egress remains behind the Microsandbox network policy.
+
 ## Host-read exceptions
 
 Pi-discovered `SKILL.md` reads are a narrow host-read exception. A standalone

package/docs/storage.md

@@ -15,6 +15,20 @@
 routed edits modify the live host directory. `none` is useful for testing path
 behavior and starts empty; it is not a retained workspace.
 
+## Inner Docker state
+
+Docker stores images, layers, containers, and build cache under
+`/var/lib/docker` on the sandbox root filesystem. It uses the `vfs` storage
+driver because nested overlay filesystems and project-backed mounts cannot be
+assumed to support `overlay2`. This state disappears when the sandbox is
+removed. It is not written to the project mount or retained Git volume, and
+separate sessions do not share an inner Docker cache.
+
+A stopped sandbox may retain that state until it is restarted or removed, but a
+retained Git workspace does not preserve it. Do not move Docker's data root
+onto the Git volume. A persistent Docker cache would need a separate managed
+volume and cleanup policy.
+
 ## Git and retained volumes
 
 Git mode never bind-mounts the host checkout. On boot, pi-microsandbox captures the

package/docs/troubleshooting.md

@@ -17,4 +17,28 @@
    command list or allow the configured network policy to reach the package
    repositories. Deny mode cannot bootstrap an image missing those commands.
 
+## Docker daemon problems
+
+`/msb status` shows the configured Docker mode, readiness, server version, and
+storage driver. Inside an active sandbox, start or recheck the daemon with:
+
+```sh
+pi-msb-docker-start 15000
+docker info
+```
+
+Startup logs are guest-local at `/var/log/pi-msb-dockerd.log`. Check the network
+prerequisites with `iptables --version` (it should report `nf_tables`), `nft
+--version`, and `sysctl net.ipv4.ip_forward` (it should be `1`). The daemon uses
+`vfs`; slower builds and higher disk use are expected compared with `overlay2`.
+Increase `memory_mib` or `docker.startup_timeout_ms` if startup is killed or
+large builds run out of memory. Small builds should have at least 1 GiB and
+larger Compose stacks should have 2 GiB or more; the default is 8 GiB.
+
+A published container port needs two mappings. Configure the outer
+`network.publish_ports` mapping before sandbox creation, then use Docker `-p`
+inside the guest. A Docker mapping by itself is not reachable from the host.
+Pull and container-egress failures under `deny` or `allowlist` are expected;
+do not bypass the outer policy or mount the host Docker socket as a workaround.
+
 For installation prerequisites, see [installation and requirements](getting-started.md). To test a live sandbox from source, see the [live test matrix](development.md#live-test-matrix).

package/extensions/pi-msb/command.ts

@@ -198,6 +198,11 @@ function fullState(state: RuntimeState): string {
   lines.push(`Image: ${info.image}`);
   lines.push(`PID: ${info.pid}`);
   lines.push(`Age: ${displayTime(info.createdAt)}`);
+  lines.push(`Docker mode: ${info.docker.mode}`);
+  lines.push(`Docker readiness: ${info.docker.readiness}`);
+  if (info.docker.version) lines.push(`Docker version: ${info.docker.version}`);
+  if (info.docker.storageDriver) lines.push(`Docker storage driver: ${info.docker.storageDriver}`);
+  if (info.docker.reason) lines.push(`Docker reason: ${info.docker.reason}`);
   if (info.seedBranch) lines.push(`Branch: ${info.seedBranch}`);
   if (info.seedSha) lines.push(`Seed SHA: ${info.seedSha}`);
   if (info.volumeName) lines.push(`Retained volume: ${info.volumeName}`);

package/extensions/pi-msb/config.ts

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { homedir as osHomedir } from "node:os";
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import type {
   Config,
   ConfigLayerInput,
@@ -19,6 +19,37 @@ const CONTROL_KEYS = new Set(["removeSecrets", "removeMounts", "removeRouteTools
 const SECRET_FIELDS = new Set(["env", "value", "allowHosts"]);
 const MOUNT_FIELDS = new Set(["type", "hostPath", "guestPath", "readonly", "options"]);
 const FORBIDDEN_CONFIG_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const PROTECTED_GUEST_ENV = new Set([
+  "BASH_ENV",
+  "CDPATH",
+  "DOCKER_CERT_PATH",
+  "DOCKER_CONFIG",
+  "DOCKER_CONTEXT",
+  "DOCKER_HOST",
+  "DOCKER_TLS",
+  "DOCKER_TLS_VERIFY",
+  "ENV",
+  "GLOBIGNORE",
+  "LD_LIBRARY_PATH",
+  "LD_PRELOAD",
+  "PATH",
+  "SHELLOPTS",
+]);
+const PROTECTED_GUEST_PATHS = [
+  "/bin",
+  "/dev",
+  "/etc/ld.so.cache",
+  "/etc/ld.so.preload",
+  "/lib",
+  "/lib64",
+  "/proc",
+  "/sbin",
+  "/sys",
+  "/usr",
+  "/run",
+  "/var/run",
+  "/var/lib/docker",
+] as const;
 
 function deepFreeze<T>(value: T): DeepReadonly<T> {
   if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
@@ -30,11 +61,11 @@ function deepFreeze<T>(value: T): DeepReadonly<T> {
 
 /** Defaults from PLAN §11.2. Values containing credentials are deliberately absent. */
 export const DEFAULT_CONFIG = deepFreeze<Config>({
-  image: "ghcr.io/hcohe/pi-microsandbox:1.0.0@sha256:00ea1e0911189815614e8a8eee36d1fd64f0f1edb39492e0bda9f273c834e59f",
+  image: "ghcr.io/hcohe/pi-microsandbox:1.1.0@sha256:ab4e99d4232f827b3f295ff3210437e01446dbb672ef0d0c78358566170ac86c",
   pullPolicy: "if-missing",
   bootstrapTools: "auto",
-  cpus: 1,
-  memoryMiB: 512,
+  cpus: 4,
+  memoryMiB: 8_192,
   idleTimeoutSec: 600,
   stopTimeoutMs: 10_000,
   detached: true,
@@ -47,6 +78,7 @@ export const DEFAULT_CONFIG = deepFreeze<Config>({
   shallowArchive: false,
   volumeQuotaMiB: 2_048,
   network: { mode: "default", allowHosts: [], allowDns: true, publishPorts: [] },
+  docker: { mode: "auto", startupTimeoutMs: 15_000 },
   secrets: [],
   mounts: [],
   blockThirdParty: true,
@@ -76,6 +108,7 @@ export interface ResolveConfigInput {
   readFile?: (path: string) => Promise<string | null>;
   exists?: (path: string) => Promise<boolean>;
   realpath?: (path: string) => Promise<string>;
+  stat?: (path: string) => Promise<{ isSocket(): boolean }>;
 }
 
 export class ConfigError extends Error {
@@ -299,6 +332,7 @@ function knownPath(path: string): boolean {
     return parts.length === 1 && CONTROL_KEYS.has(parts[0]) && !nestedNetworkRemoval;
   }
   if (parts[0] === "network") return parts.length === 1 || (parts.length === 2 && ["mode", "allowHosts", "allowDns", "publishPorts", "removeAllowHosts", "removePublishPorts"].includes(parts[1]));
+  if (parts[0] === "docker") return parts.length === 1 || (parts.length === 2 && ["mode", "startupTimeoutMs"].includes(parts[1]));
   if (parts[0] === "secrets") return parts.length === 1 || (parts.length === 2 && SECRET_FIELDS.has(parts[1]));
   if (parts[0] === "mounts") return parts.length === 1 || (parts.length === 2 && MOUNT_FIELDS.has(parts[1]));
   return ["image", "pullPolicy", "bootstrapTools", "cpus", "memoryMiB", "idleTimeoutSec", "stopTimeoutMs", "detached", "replace", "replaceTimeoutMs", "sandboxName", "mode", "cloneBranch", "cloneDepth", "shallowArchive", "volumeQuotaMiB", "blockThirdParty", "routeTools", "passThroughTools", "allowHostExecution", "allowSkillReads", "fallbackMode", "exposeSessionEnvironment", "hostEnv", "autoStart", "pruneOnStart", "showFooter", "lockDir", "hostRoAllowlist"].includes(parts[0]);
@@ -495,6 +529,9 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   if (!n(config.replaceTimeoutMs) || config.replaceTimeoutMs < 1) issues.push(issueForPath("replaceTimeoutMs", "must be positive"));
   if (!n(config.volumeQuotaMiB) || config.volumeQuotaMiB < 1) issues.push(issueForPath("volumeQuotaMiB", "must be positive"));
   if (!["auto", "git", "direct", "none"].includes(config.mode)) issues.push(issueForPath("mode", "unknown storage mode"));
+  const docker = isPlainObject(config.docker) ? config.docker : null;
+  if (!docker || !["auto", "require", "disabled"].includes(docker.mode as string)) issues.push(issueForPath("docker.mode", "must be auto, require, or disabled"));
+  if (!docker || !n(docker.startupTimeoutMs) || !Number.isInteger(docker.startupTimeoutMs) || (docker.startupTimeoutMs as number) < 1 || (docker.startupTimeoutMs as number) > 300_000) issues.push(issueForPath("docker.startupTimeoutMs", "must be an integer between 1 and 300000"));
   if (!["auto", true, false].includes(config.bootstrapTools)) issues.push(issueForPath("bootstrapTools", "must be auto, true, or false"));
   if (!["block", "host"].includes(config.fallbackMode)) issues.push(issueForPath("fallbackMode", "must be block or host"));
   const booleanFields = ["detached", "replace", "shallowArchive", "blockThirdParty", "allowHostExecution", "allowSkillReads", "exposeSessionEnvironment", "autoStart", "pruneOnStart", "showFooter"] as const;
@@ -509,7 +546,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   };
   if (stringArray("routeTools", config.routeTools)) for (const tool of config.routeTools) if (!ROUTED_TOOLS.includes(tool)) issues.push(issueForPath("routeTools", `unknown routed tool ${tool}`));
   stringArray("passThroughTools", config.passThroughTools);
-  stringArray("hostEnv", config.hostEnv);
+  if (stringArray("hostEnv", config.hostEnv)) for (const name of config.hostEnv) if (PROTECTED_GUEST_ENV.has(name)) issues.push(issueForPath("hostEnv", `must not forward protected process environment variable ${name}`));
   stringArray("hostRoAllowlist", config.hostRoAllowlist);
   const network = isPlainObject(config.network) ? config.network : null;
   if (!network || !["default", "open", "allowlist", "deny"].includes(network.mode as string)) issues.push(issueForPath("network.mode", "unknown network mode"));
@@ -521,6 +558,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
   if (!Array.isArray(config.secrets)) issues.push(issueForPath("secrets", "must be an array"));
   for (const [index, secret] of (Array.isArray(config.secrets) ? config.secrets : []).entries()) {
     if (!secret || typeof secret.env !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(secret.env)) issues.push(issueForPath(`secrets[${index}]`, "env must be a valid host environment name"));
+    else if (PROTECTED_GUEST_ENV.has(secret.env)) issues.push(issueForPath(`secrets[${index}].env`, `must not set protected process environment variable ${secret.env}`));
     if (typeof secret?.value !== "string") issues.push(issueForPath(`secrets[${index}].value`, "must be a string"));
     if (!Array.isArray(secret?.allowHosts) || !secret.allowHosts.length || secret.allowHosts.some((host: unknown) => typeof host !== "string" || !host)) issues.push(issueForPath(`secrets[${index}]`, "allowHosts must be a non-empty string array"));
   }
@@ -542,6 +580,7 @@ export function validateConfig(raw: DeepPartial<Config>): Config {
     if (typeof guest === "string" && isAbsolute(guest)) {
       const canonical = String(canonicalGuestPath(guest));
       if (isInside(canonical, "/tmp") || isInside("/tmp", canonical)) issues.push(issueForPath(`mounts[${index}].guestPath`, "must not shadow reserved /tmp paths"));
+      if (PROTECTED_GUEST_PATHS.some((reserved) => isInside(canonical, reserved) || isInside(reserved, canonical))) issues.push(issueForPath(`mounts[${index}].guestPath`, "must not shadow protected guest system or Docker runtime paths"));
     }
   }
   if (issues.length) throw new ConfigError(issues);
@@ -599,7 +638,7 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
   const canonicalPath = async (path: string, failClosed = false): Promise<string> => {
     try { return await realpath(path); }
     catch {
-      if (failClosed) throw new ConfigError(["trusted project path could not be canonicalized"]);
+      if (failClosed) throw new ConfigError(["mount or trusted project path could not be canonicalized"]);
       return resolve(path);
     }
   };
@@ -629,6 +668,12 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
   config = normalizeLegacy(config, warnings);
   // Legacy mounts participate in the same overlap/type checks as native mounts.
   config = validateConfig(config);
+  config = {
+    ...config,
+    mounts: await Promise.all(config.mounts.map(async (mount) => mount.type === "named" || mount.type === "tmpfs"
+      ? mount
+      : { ...mount, hostPath: await canonicalPath(mount.hostPath!, true) })),
+  };
 
   const projectGuestPath = String(canonicalGuestPath(resolve(input.repoRoot ?? input.cwd)));
   const projectShadowIssues = config.mounts.flatMap((mount, index) => {
@@ -649,6 +694,20 @@ export async function resolveConfig(input: ResolveConfigInput): Promise<Resolved
     .filter((mount) => mount && mount.readonly === false)
     .map((mount) => String(canonicalGuestPath(mount.guestPath ?? "")));
   const policyIssues: string[] = [];
+  const mountStat = input.stat ?? fs.stat;
+  const knownHostDockerSockets = ["/var/run/docker.sock", "/run/docker.sock"];
+  if (input.homedir ?? env.HOME) knownHostDockerSockets.push(join(String(input.homedir ?? env.HOME), ".docker", "run", "docker.sock"));
+  if (env.XDG_RUNTIME_DIR) knownHostDockerSockets.push(join(env.XDG_RUNTIME_DIR, "docker.sock"));
+  for (const [index, mount] of config.mounts.entries()) {
+    if (mount.type === "named" || mount.type === "tmpfs" || typeof mount.hostPath !== "string") continue;
+    const host = resolve(mount.hostPath);
+    let unsafe = basename(host) === "docker.sock" || knownHostDockerSockets.some((socket) => isInside(socket, host));
+    if (!unsafe) {
+      try { unsafe = (await mountStat(host)).isSocket(); }
+      catch { policyIssues.push(issueForPath(`mounts[${index}].hostPath`, "could not be safely inspected")); continue; }
+    }
+    if (unsafe) policyIssues.push(issueForPath(`mounts[${index}].hostPath`, "must not mount a host socket or Docker socket path"));
+  }
   const projectSecretFiles = new Map<string, { reference: string; canonical: string }>();
   if (Array.isArray(projectMounts)) for (const mount of projectMounts as any[]) {
     if (!mount || typeof mount.hostPath !== "string" || mount.type === "named" || mount.type === "tmpfs") continue;

package/extensions/pi-msb/control.ts

@@ -37,6 +37,7 @@ import {
   type PersistedSandboxState,
   type ResolvedConfig,
   type RuntimeExecution,
+  type RuntimePreparation,
   type RuntimeState,
   type StoragePlan,
   type ToolOperations,
@@ -267,7 +268,7 @@ function parsePort(value: string): { bind: string; host: number; guest: number }
   const numbers = parts.slice(-2).map((item) => Number(item));
   if (parts.length === 1) return { bind: "127.0.0.1", host: numbers[0], guest: numbers[0] };
   if (parts.length === 2) return { bind: "127.0.0.1", host: numbers[0], guest: numbers[1] };
-  return { bind: parts[0], host: numbers[1], guest: numbers[2] };
+  return { bind: parts[0], host: numbers[0], guest: numbers[1] };
 }
 
 function applyMount(builder: AnyRecord, mount: Config["mounts"][number]): void {
@@ -306,7 +307,7 @@ function applyNetwork(builder: AnyRecord, config: Config, sdk: MicrosandboxModul
           return destination.domain(host);
         }));
       }
-      if (network.allowDns) policy.egress((rule: AnyRecord) => rule.allowDns());
+      if (network.allowDns) policy.egress((rule: AnyRecord) => rule.udp().tcp().port(53).allowHost());
       builder.network((n: AnyRecord) => n.policy(policy));
     }
   }
@@ -347,7 +348,7 @@ function sanitizeOverride(key: string, value: unknown): unknown {
 }
 
 export function createMsbIntegration(options: MsbControlOptions): MsbIntegration {
-  const configRef = { value: { ...DEFAULT_CONFIG, network: { ...DEFAULT_CONFIG.network } } as Config };
+  const configRef = { value: { ...DEFAULT_CONFIG, network: { ...DEFAULT_CONFIG.network }, docker: { ...DEFAULT_CONFIG.docker } } as Config };
   let sessionId = options.sessionId;
   let cwd = options.cwd;
   let repoRoot: string | null = null;
@@ -531,21 +532,100 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
         bash: createBashOps({ withRuntime: async (callback) => callback({ transport, operations: undefined as never }) }),
       } as ToolOperations;
     },
-    probeAndBootstrap: async (runtime, config) => {
-      const missing = async () => {
-        const result = await Promise.all(REQUIRED_GUEST_COMMANDS.map(async (command) => ({ command, result: await runtime.transport.exec("sh", ["-lc", `command -v ${command}`]) })));
+    prepareRuntime: async (runtime, config): Promise<RuntimePreparation> => {
+      const commandsMissing = async (commandNames: readonly string[]) => {
+        const result = await Promise.all(commandNames.map(async (command) => ({
+          command,
+          result: await runtime.transport.exec("sh", ["-c", 'command -v "$1" >/dev/null 2>&1', "pi-msb-probe", command]),
+        })));
         return result.filter((item) => item.result.exitCode !== 0).map((item) => item.command);
       };
-      let commands = await missing();
+      let commands = await commandsMissing(REQUIRED_GUEST_COMMANDS);
       if (commands.length && config.bootstrapTools !== false) {
-        const apt = await runtime.transport.exec("sh", ["-lc", "command -v apt-get"]);
+        const apt = await runtime.transport.exec("sh", ["-c", 'command -v "$1" >/dev/null 2>&1', "pi-msb-probe", "apt-get"]);
         if (apt.exitCode === 0) {
           await runtime.transport.exec("apt-get", ["update", "-y"]);
           await runtime.transport.exec("apt-get", ["install", "-y", "--no-install-recommends", "bash", "git", "ripgrep", "file", "coreutils", "ca-certificates"]);
-          commands = await missing();
+          commands = await commandsMissing(REQUIRED_GUEST_COMMANDS);
         }
       }
       if (commands.length) throw new Error(`sandbox is missing required commands: ${commands.join(", ")}; install them or use bootstrapTools=true`);
+
+      const mode = config.docker.mode;
+      if (mode === "disabled") return { docker: { mode, readiness: "disabled" } };
+
+      const dockerComponents = [
+        { name: "docker", path: "/usr/local/bin/docker" },
+        { name: "dockerd", path: "/usr/local/bin/dockerd" },
+        { name: "pi-msb-docker-start", path: "/usr/local/sbin/pi-msb-docker-start" },
+      ] as const;
+      const dockerChecks = await Promise.all(dockerComponents.map(async (component) => ({
+        ...component,
+        result: await runtime.transport.exec("/usr/bin/test", ["-x", component.path]),
+      })));
+      const missingDocker = dockerChecks.filter((item) => item.result.exitCode !== 0).map((item) => item.name);
+      if (missingDocker.length) {
+        const reason = `image is missing Docker components: ${missingDocker.join(", ")}`;
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "missing", reason } };
+      }
+
+      let started = false;
+      try {
+        const result = await runtime.transport.exec(
+          "/usr/bin/env",
+          [
+            "-i",
+            "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+            "HOME=/root",
+            "/usr/local/sbin/pi-msb-docker-start",
+            String(config.docker.startupTimeoutMs),
+          ],
+          { timeoutMs: config.docker.startupTimeoutMs + 2_000 },
+        );
+        started = result.exitCode === 0;
+      } catch {
+        // Keep host-visible status bounded so transport errors cannot expose
+        // environment or secret values.
+      }
+      if (!started) {
+        const reason = "Docker daemon did not become ready; inspect /var/log/pi-msb-dockerd.log inside the sandbox";
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "unavailable", reason } };
+      }
+
+      const inspectLocalDocker = (args: string[]) => runtime.transport.exec(
+        "/usr/bin/env",
+        [
+          "-i",
+          "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+          "HOME=/root",
+          "/usr/local/bin/docker",
+          "--host=unix:///var/run/docker.sock",
+          ...args,
+        ],
+        { timeoutMs: 5_000 },
+      );
+      let version: string | undefined;
+      let storageDriver: string | undefined;
+      try {
+        const [versionResult, driverResult] = await Promise.all([
+          inspectLocalDocker(["version", "--format", "{{.Server.Version}}"]),
+          inspectLocalDocker(["info", "--format", "{{.Driver}}"]),
+        ]);
+        if (versionResult.exitCode === 0 && driverResult.exitCode === 0) {
+          version = versionResult.stdout.toString("utf8").trim().split(/\r?\n/, 1)[0]?.slice(0, 128);
+          storageDriver = driverResult.stdout.toString("utf8").trim().split(/\r?\n/, 1)[0]?.slice(0, 128);
+        }
+      } catch {
+        // Report a bounded capability error below.
+      }
+      if (!version || !storageDriver) {
+        const reason = "Docker daemon became reachable but capability inspection failed";
+        if (mode === "require") throw new Error(reason);
+        return { docker: { mode, readiness: "unavailable", reason } };
+      }
+      return { docker: { mode, readiness: "ready", version, storageDriver } };
     },
     seed: async (runtime, prepared) => seedGitVolume(runtime.transport, prepared.plan as any, prepared.bundle ?? null),
     persist: (state) => options.appendEntry?.(STATE_ENTRY, encodeSessionState(state)),
@@ -564,6 +644,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
     withRuntime: (callback) => manager.withRuntime(callback),
   };
   const effective = (): ResolvedConfig => resolved;
+  const configSnapshot = (): Config => structuredClone(configRef.value);
   const overrideEntries = (entries: readonly unknown[]): DeepPartial<Config> => {
     let result: DeepPartial<Config> = {};
     for (const entry of entries) {
@@ -608,7 +689,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
     }
     resolved = next;
     configReady = true;
-    Object.assign(configRef.value, next.config, { network: { ...next.config.network }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
+    Object.assign(configRef.value, next.config, { network: { ...next.config.network }, docker: { ...next.config.docker }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
     const state = setup.restored ?? persistenceState(options.entries?.() ?? [], sessionId);
     explicitOff = isDisabledByEnv(options.env ?? process.env);
     failureState = explicitOff ? { status: "off", info: null } : null;
@@ -616,7 +697,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
       if (!explicitOff) { await manager.setEnabled(false); failureState = { status: "off", info: null }; }
       return visibleState();
     }
-    const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: state });
+    const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: state });
     if (result.status === "unavailable") failureState = result;
     notifyState(visibleState());
     return visibleState();
@@ -644,7 +725,7 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
         await manager.setEnabled(false);
         failureState = { status: "off", info: null };
       } else {
-        const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: persistenceState(options.entries?.() ?? [], sessionId) });
+        const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: persistenceState(options.entries?.() ?? [], sessionId) });
         if (result.status === "unavailable") failureState = result;
       }
       notifyState(visibleState());
@@ -667,10 +748,10 @@ export function createMsbIntegration(options: MsbControlOptions): MsbIntegration
       }
       resolved = next;
       configReady = true;
-      Object.assign(configRef.value, next.config, { network: { ...next.config.network }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
+      Object.assign(configRef.value, next.config, { network: { ...next.config.network }, docker: { ...next.config.docker }, secrets: [...next.config.secrets], mounts: [...next.config.mounts] });
       failureState = null;
       if (!explicitOff && configRef.value.autoStart) {
-        const result = await manager.boot({ sessionId, cwd, config: configRef.value, restored: persistenceState(options.entries?.() ?? [], sessionId) });
+        const result = await manager.boot({ sessionId, cwd, config: configSnapshot(), restored: persistenceState(options.entries?.() ?? [], sessionId) });
         if (result.status === "unavailable") failureState = result;
       }
       notifyState(visibleState());

package/extensions/pi-msb/sandbox-manager.ts

@@ -10,6 +10,7 @@ import {
   type PreparedStorage,
   type PruneReport,
   type RuntimeExecution,
+  type RuntimePreparation,
   type RuntimeState,
   type SandboxManager,
   type SandboxTransport,
@@ -55,7 +56,7 @@ export interface SandboxManagerDeps {
   stopAndRemove(name: string, timeoutMs: number): Promise<void>;
   createTransport(raw: unknown): SandboxTransport;
   createOperations(transport: SandboxTransport): ToolOperations;
-  probeAndBootstrap(runtime: RuntimeExecution, config: Config): Promise<void>;
+  prepareRuntime(runtime: RuntimeExecution, config: Config): Promise<RuntimePreparation>;
   seed(runtime: RuntimeExecution, prepared: PreparedStorage): Promise<SeedResult>;
   persist(state: PersistedSandboxState): void;
   now?: () => number;
@@ -136,6 +137,7 @@ function infoFor(
   seedSha: string | null | undefined,
   createdAt: number,
   name: string,
+  preparation: RuntimePreparation,
 ): NonNullable<RuntimeState["info"]> {
   return {
     name,
@@ -149,6 +151,7 @@ function infoFor(
     seedBranch: seedBranch ?? null,
     seedSha: seedSha ?? null,
     createdAt,
+    docker: { ...preparation.docker },
   };
 }
 
@@ -192,6 +195,7 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
   let state: RuntimeState = { status: "disabled", info: null };
   let lock: LockHandle | null = null;
   let runtime: RuntimeExecution | null = null;
+  let runtimeInvalid = false;
   let sandboxName: string | null = null;
   let lastRequest: BootRequest | null = null;
   let retainedState: PersistedSandboxState | null = null;
@@ -240,6 +244,7 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
   async function disposeRuntime(): Promise<void> {
     const current = runtime;
     runtime = null;
+    runtimeInvalid = false;
     if (!current) return;
     try {
       await current.transport.dispose();
@@ -285,6 +290,12 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
     return request.config.sandboxName ?? sandboxNameFor(request.sessionId);
   }
 
+  function invalidatesRuntime(error: unknown): boolean {
+    if (!error || typeof error !== "object" || !("code" in error)) return false;
+    const code = (error as { code?: unknown }).code;
+    return code === "SANDBOX_DOWN";
+  }
+
   async function connectAndBuild(raw: unknown): Promise<RuntimeExecution> {
     const transport = deps.createTransport(raw);
     try {
@@ -396,7 +407,8 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
 
       bootedRuntime = await connectAndBuild(raw);
       runtime = bootedRuntime;
-      await deps.probeAndBootstrap(bootedRuntime, request.config);
+      runtimeInvalid = false;
+      const preparation = await deps.prepareRuntime(bootedRuntime, request.config);
 
       let seed: SeedResult | null = null;
       if (
@@ -428,6 +440,7 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
         seedSha,
         createdAt,
         name,
+        preparation,
       );
 
       // Bundle cleanup is deliberately before state publication: a successful
@@ -510,16 +523,16 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
       throw new Error(`sandbox ${sandboxName} configuration changed`);
     }
 
-    if (isRunning(inspected)) {
+    if (isRunning(inspected) && !runtimeInvalid) {
       // The boot-created transport remains authoritative while the sandbox is
       // running. Reconnecting here would replace a valid handle and dispose a
       // transport that may still have active callers.
       return runtime;
     }
 
-    // A stopped/unknown sandbox requires a replacement transport. Do not stop,
-    // start, or dispose the old one until every earlier callback has released
-    // its runtime-use reservation.
+    // A stopped/unknown sandbox or invalid running handle requires a
+    // replacement transport. Do not start or dispose the old one until every
+    // earlier callback has released its runtime-use reservation.
     await waitForActiveUses();
     let raw: unknown;
     if (isStopped(inspected)) {
@@ -530,8 +543,41 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
     }
 
     const replacement = await connectAndBuild(raw);
+    let preparation: RuntimePreparation;
+    try {
+      preparation = await deps.prepareRuntime(replacement, lastRequest.config);
+    } catch (error) {
+      try {
+        await replacement.transport.dispose();
+      } catch {
+        // Preserve the preparation error.
+      }
+      const previous = runtime;
+      runtime = null;
+      runtimeInvalid = false;
+      if (previous) {
+        try {
+          await previous.transport.dispose();
+        } catch {
+          // The preparation error remains authoritative.
+        }
+      }
+      const failedName = sandboxName;
+      sandboxName = null;
+      activePlan = null;
+      if (failedName) {
+        try {
+          await deps.stopAndRemove(failedName, lastRequest.config.stopTimeoutMs);
+        } catch {
+          throw new Error(`${redactMessage(error, lastRequest.config)}; failed to clean up the restarted sandbox`);
+        }
+      }
+      throw error;
+    }
     const previous = runtime;
     runtime = replacement;
+    runtimeInvalid = false;
+    if (state.info) state = { ...state, info: { ...state.info, docker: { ...preparation.docker } } };
     if (previous && previous !== replacement) {
       try {
         await previous.transport.dispose();
@@ -621,7 +667,7 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
     getState(): RuntimeState {
       return {
         status: state.status,
-        info: state.info ? { ...state.info } : null,
+        info: state.info ? { ...state.info, docker: { ...state.info.docker } } : null,
         ...(state.reason ? { reason: state.reason } : {}),
       };
     },
@@ -663,6 +709,9 @@ export function createSandboxManager(deps: SandboxManagerDeps): SandboxManager {
       }
       try {
         return await callback(current);
+      } catch (error) {
+        if (runtime === current && invalidatesRuntime(error)) runtimeInvalid = true;
+        throw error;
       } finally {
         releaseUse(true);
       }

package/extensions/pi-msb/types.ts

@@ -37,7 +37,12 @@ export type FallbackMode = "block" | "host";
 export type BootstrapTools = "auto" | boolean;
 export type PullPolicy = "always" | "if-missing" | "never";
 export type MountType = "dir" | "file" | "named" | "tmpfs";
+export type DockerMode = "auto" | "require" | "disabled";
 
+export interface DockerConfig {
+  mode: DockerMode;
+  startupTimeoutMs: number;
+}
 export interface NetworkConfig {
   mode: NetworkMode;
   allowHosts: string[];
@@ -74,6 +79,7 @@ export interface Config {
   shallowArchive: boolean;
   volumeQuotaMiB: number;
   network: NetworkConfig;
+  docker: DockerConfig;
   secrets: SecretConfig[];
   mounts: MountConfig[];
   blockThirdParty: boolean;
@@ -362,6 +368,17 @@ export type RuntimeStatus =
   | "off"
   | "host-fallback"
   | "disabled";
+export type DockerReadiness = "ready" | "missing" | "unavailable" | "disabled";
+export interface DockerCapabilityStatus {
+  mode: DockerMode;
+  readiness: DockerReadiness;
+  version?: string;
+  storageDriver?: string;
+  reason?: string;
+}
+export interface RuntimePreparation {
+  docker: DockerCapabilityStatus;
+}
 export interface SandboxInfo {
   name: string;
   displayId: string;
@@ -374,6 +391,7 @@ export interface SandboxInfo {
   seedBranch?: string | null;
   seedSha?: string | null;
   createdAt: number;
+  docker: DockerCapabilityStatus;
 }
 export interface RuntimeState {
   status: RuntimeStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-microsandbox",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Microsandbox-backed isolation for Pi coding tools",
   "type": "module",
   "license": "MIT",