pi-deltabox0.1.3

pi-deltabox is a Pi extension that embeds a durable deltabox-lite session directly in the Pi Node process. read, write, edit, bash, grep, find, and ls execute inside the selected confined filesystem mode. The default none native path keeps coordinator state hot, shares Pi's process environment, and uses the live mount directly for low-latency byte I/O. Linux and macOS also reuse an isolated Bash worker.

News

• 2026-10-21 — v0.1.3: Windows x64 runtime installation, PowerShell tools for MXC-isolated sessions, and WinFsp write/diff/commit/abort fixes. Windows search/list tools use PowerShell; Linux/macOS retain Bash. Isolation remains opt-in (deltabox); the default is none.

Demo

Features

• Tool-level overrides — the seven tools above run through the sandbox using Pi's official tool-override API.
• Durable review scopes — task/tool rollback points are owned by the core; skipped reviews keep the earliest rollback point across tool calls.
• In-process by default — a Node-API addon owns one resident coordinator for the Pi session; no per-tool process or JSON-RPC round trip is required.
• Persistent command worker — none-isolation bash -c calls reuse one Bash process while isolating shell state and refreshing Pi's ambient environment.
• Direct mount I/O — none-isolation native reads and writes use the validated session mount, register exact paths in one batch, and avoid Base64 copies.
• Native filesystem selection — select exact cbcow-through, cbcow-private, copy-private, or Git storage with an explicit command isolation profile. Pi stores no filesystem state.
• Bundled native runtime — npm installs the matching Linux or macOS binary and Node-API prebuild. CLI and persistent JSON-RPC transports remain available as compatibility fallbacks.
• Three review modes — review everything at the end of a task, after every tool call, or only after risky calls.
• Slash commands — /sandbox-status, /sandbox-review, /sandbox-commit, /sandbox-abort, /sandbox-skip, /sandbox-diff, /sandbox-mode.
• End-of-task nudge — when a task finishes with pending changes, Pi tells you to review, commit, or abort them.

Install

pi install npm:pi-deltabox          # once published
pi install ./pi-deltabox            # from a checkout

The npm package selects a native prebuild for Linux and macOS on x64 and arm64, or Windows on x64. Windows CB-CoW requires WinFsp. Pi uses Git Bash by default for its Bash tool on Windows. For a source checkout, build deltabox-lite, copy the addon to a .node path, and point the extension at both artifacts:

cargo build --release
cp target/release/libdeltabox_node.dylib /tmp/deltabox.node  # macOS

Configure

Windows PowerShell execution

On Windows the extension also overrides Pi's powershell tool. It runs through the same DeltaBox session and review lifecycle as file writes. Windows grep, find, and ls use PowerShell too (search patterns use .NET regular expressions and PowerShell wildcard matching). PowerShell 7 on PATH is preferred, with Windows PowerShell as fallback. Add the selected PowerShell installation to the policy's filesystem read grants when using isolation: "deltabox".

For Pi versions exposing the PowerShell tool, select it in ~/.pi/agent/settings.json:

{ "defaultTools": ["read", "powershell", "edit", "write"] }

Set "isolation": "deltabox" and the desired policy path in deltabox.json to enable MXC execution isolation. Use relative project paths in commands; the command starts in the WinFsp view, while direct backing-project access is denied. Git Bash is not a fallback when isolated PowerShell fails. The documented Windows setup uses allow_audit; restricted networking requires an explicit runtime policy, and this extension does not expose per-command network approval UI. Commands retain the native runtime's deadline; cancellation is checked before execution, not during it.

After building, run node tests/windows-powershell-real.mjs with DELTABOX_BINARY and DELTABOX_NATIVE_ADDON pointing to matching Windows builds to verify the actual tools, review transactions, and filesystem denials.

Create deltabox.json in the project, in ~/.pi/agent for user-wide defaults, or both. Project values are merged over user-wide values, including nested review settings:

{
  "transport": "native",
  "timeoutMs": 30000,
  "isolation": "none",
  "policy": "policy.toml",
  "bin": "/path/to/deltabox-lite/target/release/deltabox",
  "nativeAddon": "/tmp/deltabox.node",
  "stateDir": null,
  "runtimeDir": null,
  "filesystem": {
    "mode": "cbcow-through",
    "durability": "fast",
    "groupCommitMs": null
  },
  "review": {
    "mode": "task"
  }
}

Installed prebuilds do not need explicit bin or nativeAddon values. Paths in source-checkout configuration may be absolute or relative to the project. Configuration is snapshotted when the Pi session creates its native coordinator. stateDir and runtimeDir can pin the engine locations; null uses Deltabox defaults.

Native filesystem.mode accepts the exact modes cbcow-through, cbcow-private, copy-private, or Linux-only git. Select isolation as deltabox or none for CB-CoW/copy-private, and as bubblewrap or docker for Git. Native startup never changes the requested mode; select copy-private explicitly when CB-CoW is unavailable. Strict durability requires a CB-CoW mode; groupCommitMs is available only where the selected provider supports it.

The extension reports the requested mode, resolved mode, provider, visibility, durability, rollback guarantee, fallback reason, and taint state through /sandbox-status. Fallback and unsafe rollback conditions are also shown as Pi notifications.

Review modes

Mode	Behavior
task (default)	No per-tool prompts; review / commit / abort at the end of a task
tool	Prompt after every mutating tool call
risky	Prompt after bash, write, and edit

timeoutMs bounds CLI and JSON-RPC requests. A timeout supplied to Pi's bash tool overrides it for those compatibility transports. none-isolation commands use the resident executor's fixed 600-second deadline.

Commands

Command	Description
/sandbox-status	Show session status and pending change count
/sandbox-review	Show the pending diff
/sandbox-commit	Apply pending changes to the real project
/sandbox-abort	Discard changes back to the active review scope
/sandbox-skip	Keep changes pending and preserve the current rollback point
/sandbox-diff [from] [to]	Diff between checkpoints
/sandbox-mode task|tool|risky	Switch review mode at runtime

How it works

1. On session start, the extension loads the Node-API addon in Pi, snapshots policy and runtime configuration, and starts one resident coordinator.
2. Native operations run on the addon's Tokio blocking runtime. The route, policy, journal, filesystem state, active review, and unsandboxed Bash worker stay resident for the session lifetime. Repeated starts reuse the live client rather than creating another backend session.
3. none-isolation project reads and writes use the controlled mount directly; native Buffer methods handle fallback paths without JSON or Base64.
4. /sandbox-commit accepts the current view; /sandbox-abort restores the active review scope. In through mode, host visibility is immediate. In private modes, publication happens at commit.
5. Set "transport": "serve" or "cli" only when native loading is not available. These transports preserve the durable on-disk protocol.

Performance benchmark

The included benchmark compares native, serve, CLI, and an unsandboxed headless reference over the same review/write/read/exec/diff/abort lifecycle:

npm run bench:native -- --binary /path/to/deltabox \
  --native-addon /path/to/deltabox.node --warmups 5 --runs 30

License

Apache-2.0.

Maintainers: see RELEASING.md for the npm release process.

⭐ Star this repo if you find it is helpful!