pi-microsandbox 0.1.0 → 0.2.0

package/README.md

@@ -39,34 +39,39 @@ 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)
 
 ## Get started
 
-You'll need Pi, **Node.js 22.19.0+**, and either an Apple Silicon Mac or Linux
-with accessible KVM. Installation also needs Python and a C/C++ build toolchain;
-keep lifecycle scripts and optional dependencies enabled.
+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.
 [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

@@ -12,19 +12,87 @@ To test from source without installing the npm package globally:
 git clone https://github.com/hcohe/pi-microsandbox.git
 cd pi-microsandbox
 
-# fs-ext must compile during installation; do not use --ignore-scripts.
-npm ci
+npm ci --ignore-scripts=true
 npm run typecheck
 npm test
 npm run smoke       # extension-load smoke; no sandbox starts
 npm run check       # all three commands above
 npm audit --omit=dev
-npm pack --dry-run --json
 ```
 
 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
+contributors building or changing the addon need Python, a C compiler, and the
+platform build tools used by node-gyp (`make` on GNU Linux or Xcode command-line
+tools on macOS). On one of the three supported targets, run:
+
+```sh
+npm ci --ignore-scripts=true
+npm run build:flock
+npm run smoke:flock
+npm run check
+```
+
+The build writes
+`native/flock/prebuilds/<target>/flock.node` for the current target. These
+outputs are ignored by Git and must not be committed. CI builds
+`darwin-arm64`, `linux-x64-gnu`, and `linux-arm64-gnu` separately on native
+runners, then loads the same binary under Node 22.19.0 and Node 24.
+
+### Assemble a package from CI artifacts
+
+A complete package needs all three `flock-<target>` artifacts from one CI run.
+Download each artifact into one empty artifact root, create a staging checkout
+from the same commit's Git archive, then give both paths to the assembler:
+
+```sh
+run_id=GITHUB_ACTIONS_RUN_ID
+mkdir -p .tmp
+artifact_root="$(mktemp -d "$PWD/.tmp/flock-artifacts.XXXXXX")"
+staging="$(mktemp -d "$PWD/.tmp/package-staging.XXXXXX")"
+pack_dir="$(mktemp -d "$PWD/.tmp/package-pack.XXXXXX")"
+
+for target in darwin-arm64 linux-x64-gnu linux-arm64-gnu; do
+  gh run download "$run_id" --name "flock-$target" --dir "$artifact_root"
+done
+
+git archive HEAD | tar -x -C "$staging"
+npm run assemble:package -- "$artifact_root" "$staging"
+pack_json="$(npm pack "$staging" --json --pack-destination "$pack_dir")"
+tarball="$(node -e 'const value=JSON.parse(process.argv[1]); const results=Array.isArray(value)?value:Object.values(value); if(results.length!==1) throw new Error(`expected one pack result, got ${results.length}`); process.stdout.write(results[0].filename)' "$pack_json")"
+npm run package-smoke -- "$pack_dir/$tarball"
+```
+
+Use artifacts built from the same commit as `HEAD`. The assembler rejects
+missing, extra, or symlinked artifacts and keeps generated binaries out of the
+source checkout.
+
 ## Boot speed regression test
 
 With [`just`](https://just.systems/) installed, measure the awaited sandbox boot
@@ -71,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
 
@@ -89,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
 
@@ -98,7 +182,11 @@ canonical changelog. The first npm publication is a human-run local publish of
 the reviewed tarball with interactive npm 2FA. Subsequent releases publish
 directly to npm with OIDC only after a maintainer publishes the matching GitHub
 Release and approves the protected `npm` GitHub Environment. Release automation
-must not use a long-lived npm token.
+must not use a long-lived npm token. Release CI builds every flock artifact from
+the release commit, assembles a temporary staging tree, records each binary's
+SHA-256, smoke-tests the exact tarball on every supported target, and packs only
+once. The publish job downloads and publishes those verified bytes without
+repacking.
 
 The sandbox image workflow publishes all six AMD64 and ARM64 variants to
 `ghcr.io/hcohe/pi-microsandbox`. An `image-vX.Y.Z` Git tag publishes the

package/docs/getting-started.md

@@ -9,27 +9,26 @@ require one of these hosts:
 
 | Host | Architecture | Virtualization requirement |
 | --- | --- | --- |
-| macOS | Apple Silicon (arm64) | Apple virtualization support available to the process |
-| Linux | x86_64 or arm64 (GNU) | KVM enabled, with `/dev/kvm` accessible to the process |
-
-Windows and Intel macOS are not supported by pi-microsandbox. The upstream
-microsandbox runtime has preview Windows support, but this package deliberately
-declares only macOS and Linux. A Linux container or virtual machine also needs
-KVM passthrough or nested virtualization; many hosted environments do not
-provide it. Package loading and non-live tests do not require virtualization.
-
-Installation must run lifecycle scripts and include optional dependencies:
-
-- `fs-ext@2.1.1` compiles a native node-gyp module. Install Python and a working
-  C/C++ build toolchain (`xcode-select --install` on macOS, or a compiler,
-  `make`, and Python 3 on Linux).
-- `microsandbox@0.6.16` installs its matching native addon and runtime binaries
-  through an optional platform package. Do not use `--ignore-scripts` or omit
-  optional dependencies when installing pi-microsandbox.
-
-If the 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
+| macOS | Apple Silicon (`darwin-arm64`) | Apple virtualization support available to the process |
+| GNU Linux | x86_64 (`linux-x64-gnu`) or arm64 (`linux-arm64-gnu`) | KVM enabled, with `/dev/kvm` accessible to the process |
+
+Windows, Intel macOS, and musl Linux are not supported by pi-microsandbox. The
+upstream microsandbox runtime has preview Windows support, but this package
+deliberately supports only the three targets above. A Linux container or
+virtual machine also needs KVM passthrough or nested virtualization; many hosted
+environments do not provide it. Package loading and non-live tests do not
+require virtualization.
+
+pi-microsandbox includes a prebuilt POSIX lock addon for each supported target.
+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 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 standalone `msb` binary. These alternatives do not remove the host
 virtualization requirement.
 
 ## Install
@@ -40,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

@@ -19,11 +19,31 @@ The default is fail-closed:
   after a sandbox failure and is shown as `MSB host fallback`.
 - A project cannot replace another process's sandbox: ownership is a
   non-blocking kernel `flock` acquired before any sandbox or volume mutation.
-  Stale sandbox pruning never removes volumes.
-
-The extension entry point does not import the native SDK. Unsupported hosts can
-still load Pi and remain blocked or explicitly off. pi-microsandbox currently supports
-macOS Apple Silicon and Linux with KVM; Windows is not supported.
+  The small bundled POSIX addon is loaded lazily, has no install script, and
+  never falls back to a racy PID check. Stale sandbox pruning never removes
+  volumes.
+
+The extension entry point does not import the native SDK or load the flock
+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
 

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}`);