$ cat ~/map/pi-agent-substrate.md

pi-agent-substrate

Suspendable remote workspaces for pi and Oh My Pi, on a self-hosted Agent Substrate cluster.

extensions✓ Sep 22

From a checkout: bun install --frozen-lockfile, then pi install . (or try it with pi -e ./src/pi.ts --substrate-endpoint <url>, pointing at your deployed Environment API or a loopback tunnel); requires Pi 0.86.1 with Node 22.19+, a deployed Environment API endpoint, and an operator-provided actor template containing ate-env-guest — the package does not provision infrastructure

## TL;DR

pi-agent-substrate connects pi or Oh My Pi to a self-hosted Agent Substrate cluster so files and processes live in a suspendable remote workspace while the conversation stays local — four substrate tools, /substrate lifecycle commands, opt-in idle suspension, and explicit isolation boundaries.

## Key points

• $Remote tool surface: substrate_read, substrate_write, substrate_shell, and substrate_process cover remote files, editing, search, and Git through the sh remote shell; transfers and collected output are bounded to 1 MiB, foreground shell calls to 120 seconds, and longer jobs run with background: true and are inspected through substrate_process.
• $Environment lifecycle commands: /substrate create, attach, status, suspend, detach, and delete — deletion requires the exact attached ID and interactive confirmation and is unavailable in headless mode; idle suspension is an explicit opt-in between 0 and 86400 seconds and is blocked during active calls, tracked jobs, or uncertain process state.
• $Checkpoint/restore is verified in the README: an end-to-end proof on a self-hosted kind cluster suspends the environment to a FULL-scope snapshot and resumes with filesystem and same-process memory restored.
• $Session binding rules: resuming the same conversation with the same endpoint and atespace restores the saved attachment and process tracking; forked and new sessions do not silently inherit the attachment — attach explicitly when sharing is intentional; closing the harness neither deletes nor suspends the environment.
• $Ambiguity handling: a lost process-start response is treated as uncertain and the command is not replayed; on foreground cancellation, timeout, output overflow, or output failure the extension attempts to terminate the known remote process.
• $Security posture: use HTTPS for non-loopback endpoints with standard TLS verification left enabled, pass SUBSTRATE_TOKEN through your secret manager rather than URLs or command arguments, and note that no token is stored in the session binding.

## FAQ

## References

• README ↗

Last updated: Sep 22, 2026