Retain pi session state and agent-authored extensions on the host across sandbox removal
5.0K
Retain pi session state and agent-authored extensions on the host across sandbox removal
| Name | Required | Default | Description |
|---|---|---|---|
version | Required | — | Revision of the session-linking hook |
| Type | Required | Description | |
|---|---|---|---|
com.docker.sandbox/host-mount@1 | Required | — | |
com.docker.sandbox/lifecycle@1 | Required | — | |
pisbx run <agent> --kit sbx/pi-sessions:latestRun the following command to install sbx on your machine.
brew install docker/tap/sbxwinget install Docker.sbxThis v3 mixin Kit retains Pi conversation state and agent-authored resources on the host across sandbox removal. It composes with either the Pi workload or its agent mixin.
This Kit is built on Docker Hardened Images.
sbx run sbx/pi:latest --kit sbx/pi-sessions:latest /path/to/workspace
This kit has no create-time kit arguments.
To configure the composed agent, set arguments on its workload or agent mixin, such as
--kit-arg pi.model=anthropic/claude-sonnet-4-6. This mixin does not declare model or effort arguments.
The runtime mounts host storage at /home/agent/pi-history. Each sandbox uses a subdirectory named after that sandbox,
so simultaneous sandboxes do not share one writable session store. Reuse the sandbox name to reconnect to its retained
state.
The kit retains the declared session data, not account credentials or the agent's complete configuration directory. Conversation history can contain workspace content and tool output. Authentication stays with the composed agent kit.
The install hook refuses to replace existing nonempty session state or unexpected symlinks. Move existing state into the host-backed directory before adding this mixin to an existing environment.
sbx/pi provides the complete agent workload.sbx/pi-acp provides the ACP adapter for the composed agent.sbx/pi-mixin provides the agent overlay for a compatible workload.For the Kit format and capability contracts, see the Sandbox Kit v3 specification.
For runtime setup, see the Docker Sandboxes documentation. For provenance, SBOM, VEX, and image verification, see the Docker Hardened Images documentation.
Pi is a product of Earendil Works, Inc. Product names and logos do not imply sponsorship or endorsement.