Host

pi-sandbox commands

bin/pi-sandbox is the only supported way to run pi (spec FR-005, FR-010). It resolves values and selects compose files; every mount is declared in the compose files (path-contract.md). Put bin/ on your PATH or call it by path.

Commands#

Examples#

pi-sandbox start ~/pi/ws/private/homelab                 # new session
pi-sandbox start ~/pi/ws/private/homelab -- --continue   # continue the last session
pi-sandbox start ~/pi/ws/work/shop -- --model sonnet:high
pi-sandbox start ~/pi/ws/work/shop --with-domain private  # private memory read-only, this run only
pi-sandbox domain add club                                # new domain: ws/club/, brain/pi-memory-club/
pi-sandbox start ~/pi/ws/private/homelab --key-from-keychain
pi-sandbox selftest ~/pi/ws/private/sandbox-test
pi-sandbox stop --all

Project paths#

<project-path> may be absolute or relative. It is resolved with all symlinks followed and must then lie at <PI_ROOT>/ws/<domain>/<path>:

• <domain> is one of the configured domains (PI_DOMAINS, default private work; see Domains);
• <path> is one or more folders below the domain, at any depth, e.g. sandbox-test or git.example.org/group/repo (pi-config spec 004); every folder name matches [A-Za-z0-9._-]+ (dots allowed for host names) and none is .git;
• the project does not need to be a git repository (meeting notes, docs), but a folder inside a git repository that is not its root is refused (…/repo/src), so a subfolder never becomes its own project or memory level;
• the domain folder itself, and symlinks that land somewhere else (for example ws/private/x → an work repo), are refused.

The domain is always read from the resolved path; it picks the memory scope (spec FR-017).

Domains#

The domains are the names in PI_DOMAINS in .env (space-separated; unset or empty means private work). A name is 1–32 lowercase letters, digits or -, starts with a letter and is never core; duplicates are refused. Every command checks the list first and stops with exit 12 naming a bad entry. Each domain has ws/<name>/, brain/pi-memory-<name>/ and, for the sync, settings named by one rule: <ID> is the name in uppercase with - → _, so my-club uses BRAIN_MY_CLUB_URL, BRAIN_MY_CLUB_TOKEN_CMD, BRAIN_MY_CLUB_USER and the Keychain account brain-my-club-token. Add one with pi-sandbox domain add <name> or just domain-add <name>.

Session history#

Each domain’s session history is its own volume pi-sessions-<domain>, created on the domain’s first start/shell/selftest; at that moment the domain’s history from the old shared location moves over once (moved <n> session folder(s) of <domain> from the shared history; leftovers of no configured domain are reported with sessions clear --legacy). Before pi and shell start, sessions older than the retention are deleted (removed <n> session(s) older than &lt;d&gt; days). Retention: SESSIONS_RETENTION_DAYS (default 30) and per domain SESSIONS_<ID>_RETENTION_DAYS, whole days, 0 = keep forever. Details: state.md.

Flags#

Exit codes#

No container starts on any error. Messages start with pi-sandbox: error:.

Warnings (the session still starts)#

Summary line#

Every start, shell and selftest prints one line to stderr:

pi-sandbox: project=<path> domain=<d> memory=core:rw,<d>:rw[,<other>:ro] credentials=<stored-login|keychain> image=<repo>:<release-version> pi=<pi-version> [mode=shell|selftest]

Environment variables#

The wrapper reads .env (parsed, never executed) and passes only the variables declared in the compose files. The full list, with where each value comes from, is in path-contract.md.

just recipes#