Agent state (pi-agent-state volume)

pi’s persistent state lives in named Docker volumes (spec FR-008, FR-008a): pi-agent-state, mounted at /home/pi in every session container and shared by all domains, and one pi-sessions-<domain> per domain with that domain’s session history (pi-config spec 006). They are never in a git repo or in the image, and they survive restarts and rebuilds.

Contents#

Path in the container	What it is
`~/.pi/agent/auth.json`	Stored login (default credential method, credentials.md)
`~/.pi/agent/sessions/`	Session history (JSONL transcripts) — a separate volume per domain, `pi-sessions-<domain>`, mounted here; only this session’s domain is visible
`~/.pi/agent/trust.json`	Project trust decisions for repo-local `.pi/` config
`~/.pi/agent/npm/`, `git/`	Installed pi packages
`~/.pi/agent/settings.json`, `~/.pi/agent/mcp.json`	Links to this session’s merged files in `/run/pi-session/` (tmpfs; pi-config spec 007, config.md); re-created on every start, changes made in a session are discarded
`~/.pi/agent/mcp-auth.json`	Link to `/home/pi/.pi/domain/mcp-auth.json` in the domain’s volume `pi-domain-state-<domain>`: MCP OAuth sign-ins per domain
`HERMIT_STATE_DIR` = `/home/pi/.pi/domain/cli/hermit` (Hermit download cache, set by the entrypoint, not a link) and `~/.config/stackit`, `~/.config/hcloud`, `~/.config/gh`, `~/.kube`, `~/.talos`	Links to `/home/pi/.pi/domain/cli/stackit` / `…/hcloud` / `…/gh` / `…/kube` / `…/talos` in the domain’s volume `pi-domain-state-<domain>`: configuration and sign-in of the STACKIT and Hetzner Cloud CLIs per domain (credentials.md); a folder from before is moved to `<name>.shared`
`~/.pi/agent/AGENTS.md`	Link to this session’s stacked instructions `/run/pi-session/AGENTS.md` (tmpfs; global + levels, pi-config spec 008, config.md); re-created on every start
`~/.cache`, `~/.pi-lens`, …	Tool caches

Session history per domain (pi-config spec 006)#

Each domain keeps its session history in its own volume pi-sessions-<domain>, mounted over ~/.pi/agent/sessions (the folder pi uses). A session sees only its own domain’s history; the memory opt-in --with-domain does not change that. The wrapper creates the volume on the domain’s first start/shell/selftest.

Retention. Before pi and shell start, the entrypoint deletes this domain’s sessions whose last change is older than the retention and prints pi-sandbox: removed <n> session(s) older than <d> days when it removed any. Default 30 days (SESSIONS_RETENTION_DAYS in .env), per domain SESSIONS_<ID>_RETENTION_DAYS (<ID> as for BRAIN_<ID>_*), 0 keeps everything. A session left open but untouched for longer than the retention counts as expired; the session being started is never affected (pruning runs before it).

History from before. Until spec 006, all history was in pi-agent-state’s .pi/agent/sessions/. When a domain’s volume is created, the folders of that domain (by the working directory recorded in each session) move into it once; whatever belongs to no configured domain stays there, invisible to sessions, and is reported with pi-sandbox sessions clear --legacy as the way to delete it.

Shared across domains — known risks#

Login, installed packages and trust decisions stay in the one shared pi-agent-state (a deliberate decision, so you log in once); settings and MCP servers are per session and MCP OAuth sign-ins per domain (spec 007):

Trusting a project’s .pi/ config in one domain is recorded in the same trust.json that sessions in the other domains use.
Tool caches (~/.cache, ~/.pi-lens, …) are shared and not pruned.

Deleting#

On the host with pi-sandbox sessions …, or in a shell with the same mounts (pi-sandbox shell <project>, which sees only that project’s domain):

Goal	Command
Session history per domain (count, size, oldest, retention)	`pi-sandbox sessions list` (on the host)
Delete expired sessions now	`pi-sandbox sessions prune <domain>` or `--all`
Delete all history of a domain	`pi-sandbox sessions clear <domain>` (asks `[y/N]`)
Delete the leftover history from before spec 006	`pi-sandbox sessions clear --legacy` (asks `[y/N]`)
List this domain’s sessions (in a shell)	`ls -lt ~/.pi/agent/sessions/`
Delete one session (in a shell)	`rm ~/.pi/agent/sessions/<session-dir-or-file>`
Delete trust decisions (in a shell)	`rm ~/.pi/agent/trust.json`

Delete everything (login, history, trust, packages) from the host:

bash
pi-sandbox stop --all
docker volume rm pi-agent-state     # recreated empty on the next start
docker volume ls -q --filter name=pi-sessions- | xargs docker volume rm   # all session history

After a full reset you need to /login again, and packages are reinstalled on the next start.