pi-microsandbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-microsandbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# pi-microsandbox
+
+**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
+[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.
+
+[Get started](#get-started) · [Documentation](#documentation) · [Releases](https://github.com/hcohe/pi-microsandbox/releases)
+
+## 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.
+
+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.
+
+## Every project gets its own boundaries
+
+Your frontend app and your internal service don't 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,
+including no network access.
+
+Keep your 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.
+
+The agent gets an environment built for the job. 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.
+[Full requirements and installation help →](docs/getting-started.md)
+
+Install the Microsandbox CLI first:
+
+```sh
+curl -fsSL https://install.microsandbox.dev | sh
+```
+
+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:
+
+```sh
+pi install npm:pi-microsandbox
+```
+
+From a Git repository, start Pi with its own isolated workspace:
+
+```sh
+PI_MSB_MODE=git 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:
+
+```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.
+
+> **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.
+
+## 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) |
+| 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) |
+| Understand the isolation boundary and host access | [Safety model](docs/safety.md) |
+| Fix a sandbox that won't start | [Troubleshooting](docs/troubleshooting.md) |
+| Run tests or work on the extension | [Development](docs/development.md) |
+
+---
+
+[MIT license](LICENSE) · [Report a bug](https://github.com/hcohe/pi-microsandbox/issues) · [Report a security issue privately](SECURITY.md)

package/SECURITY.md

@@ -0,0 +1,58 @@
+# Security policy
+
+## Supported versions
+
+Before the first npm publication, security fixes are made only on the `main`
+branch. After publication, only the latest version of `pi-microsandbox`
+published on npm is supported. Older releases and unreleased forks are not
+supported; users should upgrade before reporting a problem that may already be
+fixed.
+
+## Report a vulnerability privately
+
+Do not open a public issue, discussion, or pull request for a suspected
+vulnerability. Use GitHub's private vulnerability reporting for this repository:
+
+<https://github.com/hcohe/pi-microsandbox/security/advisories/new>
+
+In the repository UI, this is **Security → Advisories → Report a
+vulnerability**. This route is available to outside reporters after the
+repository is public and private vulnerability reporting has been enabled. While
+the repository remains private, only people who already have appropriate
+repository access can use its private security-advisory workflow. If the link is
+not available, do not substitute a public report or disclose the issue in a
+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
+approval.
+
+## Keep sensitive data out of reports
+
+Provide only the minimum redacted evidence needed to reproduce the issue. Do
+not include:
+
+- passwords, API keys, npm tokens, cloud credentials, signing material, or
+  unredacted environment variables;
+- 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.
+
+## What happens next
+
+Maintainers will review the private report, ask for redacted clarification when
+needed, validate the impact, and coordinate a fix and disclosure through the
+GitHub advisory. A confirmed issue may result in a patched npm release, a GitHub
+security advisory, and release notes. GitHub Releases are the canonical
+changelog. Response and remediation times depend on severity, reproducibility,
+and maintainer availability; this policy does not promise a fixed response
+time.

package/docs/commands.md

@@ -0,0 +1,38 @@
+# Command reference
+
+[Back to README](../README.md)
+
+The extension registers `/msb`:
+
+```text
+/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>
+/msb unset <key>
+/msb reset
+/msb network allow <host...> | deny
+/msb seal
+/msb mount add <json|hostPath guestPath [--readonly]>
+/msb mount rm <guest-path>
+/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**.
+
+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`.
+
+For the narrow exceptions to sandboxed file reads, see [host-read exceptions](safety.md#host-read-exceptions).

package/docs/configuration.md

@@ -0,0 +1,80 @@
+# Configuration
+
+[Back to README](../README.md)
+
+The precedence is defaults < global < trusted project < environment < session
+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.
+
+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"
+pull_policy = "if-missing"
+bootstrap_tools = "auto"
+idle_timeout_sec = 600
+fallback_mode = "block"
+show_footer = true # Default; set false to hide the MSB footer status.
+
+[network]
+mode = "default" # default | open | allowlist | deny
+allow_dns = true
+
+# Project secrets should use references, not literals.
+[[secrets]]
+env = "NPM_TOKEN"
+value = "$ENV:NPM_TOKEN"
+allow_hosts = ["registry.npmjs.org"]
+```
+
+Important configuration behavior:
+
+- `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`
+  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
+  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.
+- `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.
+- 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.
+- 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`.
+- The legacy `host_ro_allowlist` is converted to canonical read-only mounts and
+  emits a deprecation warning.
+
+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_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
+```
+
+Do not put resolved secret values in session overrides, logs, issue reports, or
+shell history.

package/docs/development.md

@@ -0,0 +1,119 @@
+# Development and releases
+
+[Back to README](../README.md)
+
+This release requires Node.js 22.19.0 or newer. The development toolchain pins Pi 0.84.4, and the runtime dependency is pinned exactly to `microsandbox` 0.6.16.
+
+## Local development
+
+To test from source without installing the npm package globally:
+
+```sh
+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 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.
+
+## Boot speed regression test
+
+With [`just`](https://just.systems/) installed, measure the awaited sandbox boot
+path against its regression limit:
+
+```sh
+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.
+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.
+
+Run the tool directly to change the image, sample count, warm-ups, or limit:
+
+```sh
+node --experimental-strip-types scripts/test-boot-speed.mjs \
+  --image ghcr.io/hcohe/pi-microsandbox:latest \
+  --warmups 1 \
+  --runs 5 \
+  --max-ms 2000
+```
+
+Use `--json` for machine-readable output and `--help` for the complete option
+list. This is a real VM test and requires the same host virtualization support
+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:
+
+```sh
+PI_MSB_LIVE_TEST=1 ./scripts/e2e-smoke.sh
+```
+
+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`.
+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`.
+
+## Image development
+
+The image workflow derives the `base`, `node`, `python`, `rust`, `go`, and
+`default` build matrix from `default-image/variants.json`. Pull requests build
+and verify all six variants for AMD64 and ARM64. Main-branch builds publish each
+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.
+
+## Releases
+
+[GitHub Releases](https://github.com/hcohe/pi-microsandbox/releases) are the
+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.
+
+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
+write-once image cohort: `base-X.Y.Z`, `node-X.Y.Z`, `python-X.Y.Z`,
+`rust-X.Y.Z`, `go-X.Y.Z`, and `X.Y.Z` for the default variant. Package tags
+remain `vX.Y.Z` and never start image builds. Manual image workflow runs validate
+only. The workflow refuses to overwrite an existing version tag.
+
+Image and package releases are independent. Publish and verify an image cohort
+before changing the extension default to its `VERSION@sha256:DIGEST` reference.
+For the initial release, publish `image-v1.0.0`, pin its default-image digest,
+then release package `v0.1.0`. The npm workflow requires that digest-qualified
+reference, checks it against the public default tag, checks every variant and
+both platforms against the image tag commit, and verifies image provenance
+before publishing. A package
+administrator must make the GHCR package public before the package release so
+both release verification and Microsandbox can pull it without registry
+credentials.

package/docs/getting-started.md

@@ -0,0 +1,66 @@
+# Installation and requirements
+
+[Back to README](../README.md)
+
+## Requirements
+
+Pi must be installed and running on Node.js 22.19.0 or newer. Live sandboxes
+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
+virtualization requirement.
+
+## Install
+
+Install the package for the current user with Pi:
+
+```sh
+pi install npm:pi-microsandbox
+```
+
+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.
+
+For a first load, explicit off mode lets you inspect the installation without
+starting virtualization:
+
+```sh
+PI_MSB_DISABLE=1 pi
+# In Pi:
+/msb status
+```
+
+Off mode is **not sandboxed**: Pi's tools run directly on the host. Remove
+`PI_MSB_DISABLE` only after reviewing the configuration and host prerequisites.
+For an unavailable or failed sandbox, the default `fallback_mode = "block"`
+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.