pi-microsandbox 0.1.0

package/docs/images.md

@@ -0,0 +1,190 @@
+# Images
+
+[Back to README](../README.md)
+
+pi-microsandbox publishes six Ubuntu 26.04 image variants at
+`ghcr.io/hcohe/pi-microsandbox`. Every tag is a Linux multi-platform image for
+AMD64 and ARM64.
+
+## Published variants
+
+`VERSION` below is the independent image version, such as `1.0.0`. Release
+tags are write-once. Latest tags are mutable development tags built from `main`.
+Push an exact `image-vVERSION` Git tag to publish a release cohort. Package
+`vX.Y.Z` tags do not invoke image builds, and manual workflow runs validate only.
+
+| Variant | Contents | Release tag | Latest tag |
+| --- | --- | --- | --- |
+| `base` | Required guest commands and CA certificates, without a 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` |
+| `go` | Base plus Go 1.26.8 and cgo build support | `go-VERSION` | `go-latest` |
+| `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.
+
+Select a variant in trusted project configuration:
+
+```toml
+# .pi-msb.toml
+image = "ghcr.io/hcohe/pi-microsandbox:python-1.0.0"
+pull_policy = "if-missing"
+```
+
+If `image` is omitted, pi-microsandbox uses the configured `default` variant
+release, qualified by both its `VERSION` tag and immutable index digest. Image
+versions are independent of the installed package version. If `pull_policy` is
+omitted, `"if-missing"` is used: Microsandbox pulls the image only when that
+exact reference is absent from its cache. Use `"always"` to check a registry for
+an updated mutable tag, or `"never"` to require a cached local image.
+
+## How the images are assembled
+
+[`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.
+
+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
+installer, its functional checks, and every image that uses it aligned.
+
+Release builds pin the Ubuntu multi-platform image digest and a dated Ubuntu apt
+snapshot shared by every variant. The snapshot pin applies only while the image
+is assembled. Published images restore Ubuntu's normal apt sources so projects
+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
+`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.
+
+Microsandbox supports registry images and images loaded into its own local
+cache. Images in the Docker daemon are not automatically visible to
+Microsandbox.
+
+### Publish to an OCI registry
+
+Start from a versioned base tag so the guest contract does not change when
+`main` is rebuilt:
+
+```dockerfile
+FROM ghcr.io/hcohe/pi-microsandbox:base-1.0.0
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends jq \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+Build and push for the current host architecture with Docker:
+
+```sh
+docker build -t registry.example.com/team/pi-image:1.0.0 .
+docker push registry.example.com/team/pi-image:1.0.0
+```
+
+Or publish both supported architectures with Buildx:
+
+```sh
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --tag registry.example.com/team/pi-image:1.0.0 \
+  --push .
+```
+
+Then select it in `.pi-msb.toml`:
+
+```toml
+image = "registry.example.com/team/pi-image:1.0.0"
+pull_policy = "if-missing"
+```
+
+For a private registry, configure authentication on the host with Microsandbox,
+for example with `msb registry login`, or in
+`~/.microsandbox/config.json`. Registry pull credentials belong in
+Microsandbox configuration, not in pi-microsandbox guest `secrets`. See the
+Microsandbox [image guide](https://docs.microsandbox.dev/images/overview) and
+[configuration reference](https://docs.microsandbox.dev/configuration).
+
+### Load a local Docker image
+
+Build the image, then transfer a Docker archive into the Microsandbox cache and
+assign a local tag:
+
+```sh
+docker build -t pi-image:dev .
+docker save pi-image:dev | msb load --tag pi-image:local
+```
+
+The file form is useful when a pipeline cannot be used:
+
+```sh
+docker save -o pi-image.tar pi-image:dev
+msb load --input pi-image.tar --tag pi-image:local
+```
+
+Use the local reference without contacting a registry:
+
+```toml
+image = "pi-image:local"
+pull_policy = "never"
+```
+
+`pull_policy = "if-missing"` also uses the loaded image while it remains in the
+cache, but may try a registry if it is removed. The Microsandbox
+[local image guide](https://docs.microsandbox.dev/examples/docker/local-images)
+documents the same transfer requirement and `msb load` forms.
+
+## Add a language variant
+
+A new language needs all three of these changes:
+
+1. Add an executable `default-image/install/<language>.sh`.
+2. Add an executable `default-image/verify/<language>.sh`.
+3. Add the variant and its toolchain composition to
+   `default-image/variants.json`.
+
+Names become filenames and image tags. Use at most 48 characters: start with a
+lowercase letter, then use only lowercase letters, digits, and hyphens. Do not
+use path syntax, underscores, or the reserved names `base`, `default`,
+`dispatch`, or a name beginning with `_`.
+
+Pin downloaded tool versions. Record and verify SHA-256 checksums for both AMD64
+and ARM64 artifacts, using the helpers in `install/_common.sh`. Do not pipe
+network downloads into a shell. The verifier must test native functionality,
+not only version output. For example, compile and run a native extension or a
+small program. Add the language to the `default` variant's `toolchains` only if
+it should become part of the complete image; do not copy its packages into a
+second default-only installer.
+
+Validate metadata and shell scripts locally:
+
+```sh
+node scripts/image-variants.mjs matrix
+shellcheck -e SC1091 default-image/install/*.sh default-image/verify/*.sh
+```
+
+Build a representative variant with the same context and build arguments as CI.
+The Dockerfile runs its functional verifier during the build:
+
+```sh
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  --build-arg IMAGE_VARIANT=node \
+  --build-arg "TOOLCHAINS=node" \
+  --build-arg IMAGE_VERSION=dev \
+  --file default-image/Dockerfile \
+  default-image
+```
+
+Repeat with the new variant and its exact space-separated toolchain composition.
+Build the `default` variant too if its composition changed.

package/docs/safety.md

@@ -0,0 +1,39 @@
+# Safety model
+
+[Back to README](../README.md)
+
+The default is fail-closed:
+
+- A valid, trusted project configuration is resolved before a sandbox is
+  started. A boot or image/tool failure blocks the seven routed tools (`read`,
+  `write`, `edit`, `ls`, `find`, `grep`, and `bash`).
+- `mode = "auto"` is retained as an alias for `"direct"`; both use a
+  same-absolute-path read/write bind. `mode = "git"`, `"direct"`, and
+  `"none"` select those behaviors explicitly.
+- `execution_target = "host"` is an opt-in escape for routed tool calls. While
+  a sandbox is active it requires an interactive approval for the exact tool,
+  working directory, and recursively sorted arguments. It is not available in
+  headless operation and is never silently selected.
+- `/msb off` is an explicit host-mode handoff and does not prompt. This is
+  different from `fallback_mode = "host"`, which automatically uses host tools
+  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.
+
+## Host-read exceptions
+
+Pi-discovered `SKILL.md` reads are a narrow host-read exception. A standalone
+skill grants only its exact file; a directory skill grants regular files
+canonically below its directory. Symlink escapes, devices, sockets, and
+unrelated host paths are denied. A successful sandbox Bash/grep result may
+record one exact generated `details.fullOutputPath`; neighboring files do not
+become readable.
+
+## Reporting vulnerabilities
+
+Report suspected vulnerabilities privately. See the [security policy](../SECURITY.md); do not open a public issue.

package/docs/storage.md

@@ -0,0 +1,57 @@
+# Storage modes and retained work
+
+[Back to README](../README.md)
+
+## Storage modes
+
+| Mode | Guest view | Host effect of routed writes |
+| --- | --- | --- |
+| `git` | A named volume at the repository root, with the same absolute path | Volume only |
+| `direct` | The current directory bind-mounted at the same absolute path | Host directory |
+| `none` | An empty tmpfs at the same absolute path | No host files; changes disappear with the sandbox |
+| `auto` | Same as `direct` | Host directory |
+
+`direct` is intentionally a warning-level escape from the Git isolation model:
+routed edits modify the live host directory. `none` is useful for testing path
+behavior and starts empty; it is not a retained workspace.
+
+## Git and retained volumes
+
+Git mode never bind-mounts the host checkout. On boot, pi-microsandbox captures the
+committed `HEAD` (and selected branch) into a temporary verified Git bundle,
+copies it into the guest, and seeds a named volume mounted at the repository's
+absolute root. Untracked files, including `.env`, and working-tree edits are
+not in that bundle. The temporary host and guest bundle files are removed after
+seeding, including failure paths.
+
+Edits and commits made in Git mode land in the retained volume. The host
+checkout is not changed by ordinary routed tools. A normal Pi session shutdown
+removes the sandbox but keeps the managed volume; the next boot reuses it only
+when the complete session/schema/mode/cwd identity matches. A copied or forked
+session state is rejected by the full session ID and gets a different resource
+identity.
+
+The SDK's `VolumeHandle` returned by `Volume.get()` does not expose a host
+path. pi-microsandbox therefore refuses to fabricate one: a newly created volume
+may show its path, while a later retained-volume lookup may not support
+`/msb volumes ls` or volume enrichment. The volume remains mountable by name
+and is never automatically deleted. Use the path recorded at creation time or
+the microsandbox volume tooling when host-side inspection is required.
+
+To manually synchronize a retained checkout, use a host-side fetch deliberately
+(the command is not performed automatically by pi-microsandbox):
+
+```sh
+REPO=/absolute/path/to/checkout
+VOLUME_PATH=/path/returned-for-the-managed-volume
+BRANCH=$(git -C "$REPO" branch --show-current)
+
+git -C "$VOLUME_PATH" remote remove host 2>/dev/null || true
+git -C "$VOLUME_PATH" remote add host "$REPO"
+git -C "$VOLUME_PATH" fetch --no-tags host "$BRANCH"
+# Review before changing the retained checkout:
+git -C "$VOLUME_PATH" log --oneline --decorate --all -10
+```
+
+The host repository is an input to this explicit sync operation. Do not add a
+host checkout bind mount to Git mode.

package/docs/troubleshooting.md

@@ -0,0 +1,20 @@
+# Recovery and troubleshooting
+
+[Back to README](../README.md)
+
+1. Run `/msb status` and `/msb logs`.
+2. If the state is `unavailable (blocked)`, fix the displayed configuration,
+   image, virtualization, or missing-tool error and run `/msb reload`.
+3. If a process died, a later startup or `/msb prune` can remove its labelled
+   sandbox after the owner lock is free. The named volume is retained.
+4. If a same-name resource has different managed labels, pi-microsandbox refuses to
+   attach or replace it. Remove only a verified managed, unmounted volume with
+   `/msb volumes rm NAME --yes`.
+5. On unsupported virtualization hosts, use `PI_MSB_DISABLE=1` for explicit host
+   mode or configure `fallback_mode = "host"` knowingly. The latter remains
+   visibly distinct from `/msb off`.
+6. For bootstrap failures, use an image that already contains the required
+   command list or allow the configured network policy to reach the package
+   repositories. Deny mode cannot bootstrap an image missing those commands.
+
+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).