Host

Onboarding a project

How to add a project so pi-sandbox start works on the first try (spec US4, FR-002, FR-026).

Convention#

~/pi/ws/<domain>/<path>/      a project folder at any depth below its domain folder, e.g.
                              ws/private/sandbox-test or ws/private/git.example.org/group/repo

• Clone on the host, with your normal host credentials: git clone <url> ~/pi/ws/<domain>/<host>/<group>/<repo> (or flat: ~/pi/ws/<domain>/<repo>). The sandbox has no push credentials; you push from the host after reviewing the agent’s local commits.
• Every folder name must match [A-Za-z0-9._-]+. A project does not have to be a git repository (meeting notes, docs), but you cannot open a subfolder inside a repository.
• No symlinks that land elsewhere: the start command resolves the real path (a symlink from ws/private into an work repo would otherwise borrow the wrong memory scope).
• ws/ itself is not a git repo.

Before the first session#

1. work projects only — sub-processor check (FR-026). Confirm that the model provider you use (for example Anthropic) is approved as a sub-processor for this customer. If it is not, or you are not sure, do not use the project with the sandbox — ask first. Record nothing about people while doing this check.
2. Credentials in the project. Anything in the working tree is readable by the agent: .env files, local config with tokens, keys. Remove what the task doesn’t need. pi-sandbox start warns when a git remote URL embeds credentials (https://user:token@…); replace such remotes on the host (git remote set-url origin https://host/path.git).
3. Project-local pi config. If the repo contains .pi/settings.json, .pi/extensions or similar, pi asks whether to trust the project. Trust it only after reading what it would load: trusted project extensions run code in the sandbox, and the trust decision is stored in the shared agent state, so it also applies in sessions of the other domain (state.md). AGENTS.md / CLAUDE.md in the project are always loaded as context.

First start#

pi-sandbox start ~/pi/ws/<domain>/<repo>

The summary line shows the inferred domain and the memory scope, for example domain=work memory=core:rw,work:rw. If it refuses:

Project memory appears in ~/pi/brain/pi-memory-<domain>/<path>/ on the first write; levels above the project (host, group) can hold their own memory (see memory.md). To fill memory deliberately, run /memory-seed in a session.

Adding a new domain#

Domains are configured, not coded (pi-config spec 005). For a domain club:

1. pi-sandbox domain add club (or just domain-add club): adds club to PI_DOMAINS in .env and creates ~/pi/ws/club/, the memory store ~/pi/brain/pi-memory-club/ (git repo with the usual files, no commit yet) and the configuration store ~/pi/config/pi-config-club/ (settings and MCP servers per level, config.md; push it yourself to a private remote when you start using it).
2. Create a private remote repository for the store, then set BRAIN_CLUB_URL=<https url> in .env (and BRAIN_CLUB_USER=<user> if the token has no user: prefix).
3. Store the push token: security add-generic-password -s pi-sandbox -a brain-club-token -U -w, or set BRAIN_CLUB_TOKEN_CMD in .env.
4. pi-sandbox memory-sync club reviews and pushes the starter files (first commit).
5. pi-sandbox domain list shows what each domain has; clone projects into ~/pi/ws/club/….

For a domain that exists already (e.g. private, work from before spec 007), create the configuration store with pi-sandbox config init <domain>.

Removing a domain is manual: take it out of PI_DOMAINS; its folders stay until you delete them.