pi-microsandbox 0.1.1 → 0.3.0

package/README.md

@@ -2,45 +2,71 @@
 
 **Let your agents work. Stop babysitting every command.**
 
-Give an agent a task and get on with your day. Give a few agents different tasks
-and let them work in parallel. Come back to review the results.
-
-pi-microsandbox uses [Microsandbox](https://microsandbox.dev/) to run
+Give an agent a task and get on with your day. pi-microsandbox uses
+[Microsandbox](https://microsandbox.dev/) to run
 [Pi](https://github.com/earendil-works/pi)'s file and shell tools in lightweight
 microVMs. Microsandbox is an open-source, local-first runtime for isolating
 untrusted workloads, with a separate Linux kernel for each sandbox.
 
-In Git mode, each separate Pi session gets its own workspace instead of editing
-your host checkout. Each project can define its own environment and safety
-boundaries. Set them up once, then let the agents get to work.
+Each project can define its own environment and safety boundaries. Set them up
+once, then let the agent get to work.
 
 [Get started](#get-started) · [Documentation](#documentation) · [Releases](https://github.com/hcohe/pi-microsandbox/releases)
 
+## Try it
+
+Run Pi with pi-microsandbox for one session, without installing it:
+
+```sh
+pi -e npm:pi-microsandbox
+```
+
 ## Less supervision. More work getting done.
 
-- Run multiple agents in separate Pi sessions. Git mode keeps their workspaces apart, so ordinary sandboxed edits don't collide in your host checkout.
-- Let routine file and shell work happen inside the sandbox. Host execution stays an explicit escape, with approval required while the sandbox is active.
-- Step away without throwing away the work. Git-mode files survive sandbox shutdown, ready when you resume the matching session.
-- If the sandbox can't start, routed tools stop by default. They don't quietly run on your host instead.
+- Let routine file and shell work happen inside the sandbox. Host execution
+  stays an explicit escape, with approval required while the sandbox is active.
+- Work at the same path inside and outside the VM. Sandboxed writes appear in
+  the host checkout immediately, with no export step.
+- If the sandbox cannot start, routed tools stop by default. They do not quietly
+  run on your host instead.
 
-You still review what the agents produce. The point is to spend your attention
-on the results, rather than supervise every step along the way.
+You still review what the agent produces. The point is to spend your attention
+on the results rather than supervise every step along the way.
+
+## One workspace behavior
+
+There are no workspace modes. If Pi starts inside a Git worktree,
+pi-microsandbox mounts the whole worktree root read/write at the same lexical
+path in the guest. If Pi starts outside Git, it mounts the current working
+directory itself. Commands start in the original current working directory.
+
+This is a VM boundary, not checkout isolation. The selected root is fully
+visible, including `.git`, secrets such as `.env`, untracked files, and sibling
+directories. Writes change the host immediately. Multiple sessions using the
+same checkout share those files and can conflict; use separate host worktrees
+or checkouts when you need independent changes. Containers started inside the
+microVM can also reach the mounted workspace.
+
+[Understand workspace storage and legacy-volume recovery →](docs/storage.md)
 
 ## Every project gets its own boundaries
 
-Your frontend app and your internal service don't need the same sandbox.
+Your frontend app and your internal service do not need the same sandbox.
 Choose a [published variant or custom image](docs/images.md) with the tools a
 project needs, allow only the network hosts it should reach, and configure its
-file mounts and secrets. Another project can have a completely different setup,
+extra file mounts and secrets. Another project can have a different setup,
 including no network access.
 
-Keep your everyday defaults in global config and project-specific settings in
+Keep everyday defaults in global config and project-specific settings in
 `.pi-msb.toml`. Trusted project config layers over those defaults; environment
-variables and session overrides let you adjust a particular run without
-rewriting the project's setup.
+variables and session overrides let you adjust a run without rewriting the
+project 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. Nested containers can still access the mounted
+workspace and remain subject to the outer network policy.
 
 [Configure your project's sandbox →](docs/configuration.md)
 
@@ -50,67 +76,56 @@ 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.
+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.
 
-Then install 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.
 
-```sh
-pi install npm:pi-microsandbox
-```
-
-From a Git repository, start Pi with its own isolated workspace:
+Start Pi from the directory where you want to work:
 
 ```sh
-PI_MSB_MODE=git pi
+cd /path/to/project
+pi
 ```
 
-Git mode starts from committed `HEAD`. Commit any changes you want the agent to
-see first; untracked files such as `.env` and uncommitted edits stay out of the
-initial copy. An existing retained workspace is reused for a matching session.
-
-Once you're in Pi:
+Once you're in Pi, inspect the selected workspace root:
 
 ```text
 /msb status
 ```
 
-Give Pi a task. To work on another task in parallel, start a separate Pi session
-with the same command in another terminal. Each session gets its own Git-mode
-workspace.
-
-When you're ready to review an agent's work, export a file to a new destination:
-
-```text
-/msb export src/example.ts --to ../sandbox-review
-```
-
-Exports ask for confirmation and won't overwrite existing destinations.
-See [storage and retained work](docs/storage.md) for the details.
+> **Host execution is separate.** `/msb off` explicitly hands tools to the
+> host. `fallback_mode = "host"` opts into automatic host execution after a
+> sandbox failure. Neither control changes the workspace mount, and neither is
+> sandboxed. The default fallback blocks tools when startup fails.
 
-> **Choose your boundary.** The default storage mode is `direct`, which writes
-> to your host directory. The command above explicitly selects `git` isolation.
-> `/msb off` turns sandboxing off; `fallback_mode = "host"` opts into automatic
-> host execution after a failure. Neither is sandboxed.
+Upgrading from a release that used named Git volumes requires a manual recovery
+check. Before upgrading, use the old `/msb volumes` and `/msb export` commands
+to inventory and copy retained work. After upgrading, use Microsandbox's own
+tooling to recover or remove legacy volumes; they are never deleted
+automatically. See [workspace storage](docs/storage.md).
 
 ## Documentation
 
 | When you want to… | Read |
 | --- | --- |
 | Install or check host support | [Getting started](docs/getting-started.md) |
-| Choose a workspace mode or recover retained work | [Storage](docs/storage.md) |
+| Understand the workspace mount or recover legacy volumes | [Storage](docs/storage.md) |
 | Choose an image variant or build a custom image | [Images](docs/images.md) |
 | Set up networking, secrets, mounts, or other options | [Configuration](docs/configuration.md) |
 | Look up an `/msb` command | [Command reference](docs/commands.md) |

package/SECURITY.md

@@ -26,7 +26,7 @@ public channel.
 A useful report includes the affected pi-microsandbox version or commit, Pi and
 Node.js versions, host operating system and architecture, virtualization setup,
 impact, and minimal reproduction steps. State whether the behavior requires a
-particular storage mode, network policy, fallback setting, or host-execution
+particular workspace layout, network policy, fallback setting, or host-execution
 approval.
 
 ## Keep sensitive data out of reports
@@ -39,13 +39,17 @@ not include:
 - resolved secret values from `$ENV:` or `$FILE:` references;
 - complete sandbox logs, configuration dumps, session files, or command output
   that may contain secrets;
-- retained-volume contents, source code, `.env` files, or other private user
-  data that is not essential to the report.
-
-If a real secret may have been exposed, revoke or rotate it first. Use synthetic
-values in the reproduction and describe omitted material rather than attaching
-it. Remember that GitHub advisory participants can read uploaded artifacts, so
-a private report is not a reason to include unnecessary secrets.
+- workspace or legacy-volume contents, source code, `.env` files, or other
+  private user data that is not essential to the report.
+
+If a real secret may have been exposed, revoke or rotate it first. The selected
+workspace is mounted read/write: inside Git it includes the entire worktree,
+including `.git`, secrets, untracked files, and sibling directories; outside
+Git it is the current directory. Writes reach the host immediately, concurrent
+sessions share the checkout, and nested containers can access the mount. Use
+synthetic values in the reproduction and describe omitted material rather than
+attaching it. Remember that GitHub advisory participants can read uploaded
+artifacts, so a private report is not a reason to include unnecessary secrets.
 
 ## What happens next
 

package/docs/commands.md

@@ -8,9 +8,6 @@ The extension registers `/msb`:
 /msb status
 /msb on | off | reload
 /msb prune
-/msb volumes ls
-/msb volumes rm <managed-name> [--yes]
-/msb export <paths...> [--to dir] [--yes]
 /msb logs [tail-lines]
 /msb config
 /msb set <key> <value>
@@ -23,16 +20,23 @@ 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
-display abbreviations only. `/msb prune` walks all SDK list pages and reports
-removed, kept, and error entries; **volumes are never pruned**.
+`/msb status` reports the full sandbox name, mounted workspace root, image, PID,
+age, and Docker mode, readiness, version, and storage driver. Six-character IDs
+in UI text are display abbreviations only. There are no workspace modes.
 
-Volume removal is the sole destructive volume path. It requires a managed,
-unmounted volume and an owner lock. Confirmation displays path, branch, last
-commit, and dirty-count metadata; use `--yes` only when the command is running
-without UI and the target has already been verified. Export rejects paths outside
-the project and existing destinations; it also requires confirmation or
-`--yes`.
+`/msb prune` walks all SDK list pages and reports removed, kept, and error
+entries. It can remove guarded stale sandboxes, including old-schema managed
+sandboxes, but it never removes legacy named volumes.
 
-For the narrow exceptions to sandboxed file reads, see [host-read exceptions](safety.md#host-read-exceptions).
+`/msb off` explicitly switches to unsandboxed host execution. It is separate
+from `fallback_mode = "host"`, which opts into automatic host execution after a
+sandbox failure. With the default blocking fallback, startup failures fail
+closed and routed tools do not silently run on the host.
+
+The former `/msb volumes` and `/msb export` commands are not available. Files in
+the current workspace already live on the host. Legacy named volumes from older
+releases require manual inspection, recovery, and removal with Microsandbox's
+own tooling; see [workspace storage](storage.md#upgrading-from-named-git-volumes).
+
+For the narrow exceptions to sandboxed file reads, see
+[host-read exceptions](safety.md#host-read-exceptions).

package/docs/configuration.md

@@ -7,17 +7,19 @@ CLI overrides. Global configuration is `$XDG_CONFIG_HOME/pi-msb/config.toml`
 (or `~/.config/pi-msb/config.toml`) plus the optional `PI_MSB_CONFIG_FILE` in
 the same layer. A trusted project may use the nearest `.pi-msb.toml` or
 `<Pi CONFIG_DIR_NAME>/msb.toml`, stopping at the Git root. Untrusted project
-configuration is ignored with a warning.
+configuration is ignored with a warning, except that removed workspace settings
+still stop startup before any direct host write can occur.
 
 TOML uses snake_case; environment variables use `PI_MSB_` with `__` for nesting.
 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"
@@ -35,32 +41,63 @@ allow_hosts = ["registry.npmjs.org"]
 
 Important configuration behavior:
 
+- There are no workspace modes or storage selection settings. Inside a Git
+  worktree, the whole worktree root is mounted read/write at the same lexical
+  guest path; elsewhere, the current directory is mounted. Commands retain the
+  original cwd, and writes reach the host immediately. The removed `mode`,
+  `clone_branch`, `clone_depth`, `shallow_archive`, and `volume_quota_mib`
+  settings, including `PI_MSB_MODE`, are startup errors rather than ignored
+  compatibility options.
 - `show_footer = true` uses Pi's single custom-footer slot so the MSB status can
   appear in the upper-right corner. It replaces Pi's built-in footer (or another
   extension's custom footer), preserves the standard location, usage, model,
   and shared status fields, but cannot show Pi-only indicators such as the
   auto-compaction and experimental-feature markers.
-- The default image is the complete Node.js, Python, Rust, and Go `1.0.0`
+- The default image is the complete Node.js, Python, Rust, and Go `1.1.0`
   variant, pinned to its immutable multi-platform digest. Image releases have
-  an independent version stream; the initial package remains `0.1.0`. The
-  default `pull_policy = "if-missing"` pulls only when that exact reference is
+  an independent version stream from package releases. The default
+  `pull_policy = "if-missing"` pulls only when that exact reference is
   absent from the Microsandbox cache. `"always"` and `"never"` are also
   supported.
   See [Images](images.md) for all published variants, exact tag patterns,
   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`.
+  selected workspace root must be read-only unless a global/session policy
+  authorizes the 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.
 
@@ -68,9 +105,10 @@ Useful environment controls include:
 
 ```sh
 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
@@ -81,9 +103,9 @@ just test-boot-speed
 ```
 
 The tool performs one unmeasured warm-up, then three fresh boots using the
-default prepared image. It forces direct mode, disables guest networking and
-stale-resource pruning, and sets `bootstrap_tools = false` so the result
-measures repeat boot and readiness rather than an image pull or package install.
+default prepared image. It disables guest networking and stale-resource
+pruning, and sets `bootstrap_tools = false` so the result measures repeat boot
+and readiness rather than an image pull or package install.
 The p95 must be at most 2,000 ms. Every sandbox is shut down and removed. If
 lifecycle cleanup fails, the test fails and retains its reported `.tmp` directory
 for recovery instead of claiming success.
@@ -105,9 +127,9 @@ as the live matrix.
 ## Live test matrix
 
 From a source checkout, the live matrix is opt-in because it can pull an image,
-start VMs, create retained resources, and use network and disk capacity. Run it
-only from a trusted checkout on a disposable test host after reviewing the
-script:
+start VMs, write through the host workspace mount, and use network and disk
+capacity. Run it only from a trusted checkout on a disposable test host after
+reviewing the script:
 
 ```sh
 PI_MSB_LIVE_TEST=1 ./scripts/e2e-smoke.sh
@@ -117,14 +139,24 @@ 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`.
+The workspace scenarios must show that a Git subdirectory mounts the whole
+worktree, a non-Git cwd mounts itself, and routed writes appear immediately on
+the host. They also cover off/on and reload, stale-sandbox pruning, fail-closed
+boot errors, and approved host execution. Docker release validation must cover
+daemon readiness, bridge DNS and HTTPS, user-defined networking, Buildx,
+Compose, idle wake, double port publishing, nested-container access to the
+workspace, and network enforcement for deny and allowlist policies. A skipped
+scenario is not release evidence.
 
 ## Image development
 
@@ -135,7 +167,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.
@@ -59,7 +64,19 @@ blocks routed tools rather than silently running them on the host. Keep that
 default for a fail-closed setup. `fallback_mode = "host"` is an explicit,
 visibly labelled opt-in to automatic unsandboxed execution.
 
-The public package is named `pi-microsandbox`. Existing technical interfaces
-retain the shorter `msb` name for compatibility, including `/msb`,
-`PI_MSB_*`, `.pi-msb.toml`, configuration directories, and managed-resource
-labels. Existing configuration and retained resources therefore keep working.
+The public package is named `pi-microsandbox`. Current technical interfaces
+retain the shorter `msb` name, including `/msb`, `PI_MSB_*`, `.pi-msb.toml`,
+configuration directories, and managed-resource labels.
+
+There are no workspace modes. Starting inside Git mounts the entire worktree
+root read/write; starting elsewhere mounts the cwd. The mount uses the same
+lexical guest path, commands retain their original cwd, and writes reach the
+host immediately. This exposes `.git`, secrets, untracked files, and sibling
+directories. Concurrent sessions share a checkout, and nested containers can
+reach the mount.
+
+Before upgrading from a release with named Git workspaces, use its `/msb
+volumes` and `/msb export` commands to inventory and copy retained work. The new
+release neither reconnects nor deletes legacy volumes. Recover or remove them
+manually with Microsandbox tooling after confirming their contents. Removed
+settings such as `mode` and `PI_MSB_MODE` are errors, not compatibility aliases.

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
@@ -62,8 +66,13 @@ 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
+A custom image must provide `bash`, `sh`, `rg`, `file`, `cat`, `mkdir`, and
+`rm`. Git is a useful developer tool and remains in the published images, but
+workspace setup no longer requires it inside the guest. 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 Git and CA certificates if guest commands need 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.