Session

Host ↔ Container Path & Mount Contract

Single source. This file is the one shared contract between pi-docker-sandbox, which implements it, and pi-config / brain/, which consume it (spec FR-021). Both READMEs link here. Change a mount only together with this table, in the same commit. Design-time origin: pi-config/specs/001-pi-workspace-setup/contracts/path-contract.md.

Host layout (root PI_ROOT, default ~/pi)#

~/pi/
├── pi-config/            # agent config repo; only agent/ is mounted
│   └── agent/
├── pi-docker-sandbox/    # container definition + bin/pi-sandbox
├── brain/
│   ├── pi-memory-core/
│   ├── pi-memory-private/
│   ├── pi-memory-work/
│   └── pi-memory-<name>/ # one per further domain in PI_DOMAINS (pi-config spec 005)
├── config/               # pi-config-<domain>/: settings and MCP servers per level (spec 007);
│                         #   read on the host, never mounted
└── ws/                   # not a git repo
    ├── private/<path>/   # any depth, e.g. sandbox-test or git.example.org/group/repo
    ├── work/<path>/       # e.g. <host>/<customer>/<project | meeting notes | docs>
    └── <name>/<path>/    # any further configured domain

The domains are PI_DOMAINS in .env (default private work); pi-sandbox domain add <name> creates ws/<name>/ and brain/pi-memory-<name>/ (commands.md).

PI_ROOT is set in pi-docker-sandbox/.env. The default is derived from the location of pi-docker-sandbox (its parent directory). The wrapper refuses to start if PI_ROOT/pi-config/agent is missing and names the expected path (Edge Cases).

Session container mounts#

The root filesystem is read-only. Nothing else is mounted. These are explicitly forbidden:

• $HOME
• ~/.ssh and SSH_AUTH_SOCK — push does not mount them: the wrapper reads a key file or command (or a token command) named in .env and passes the credential through the environment of that one session (credentials.md)
• ~/.pi/agent
• /var/run/docker.sock
• ~/.gitconfig and any host git credential helper
• the macOS Keychain and password-manager CLIs (secrets are read on the host by bin/pi-sandbox and passed by name only, never mounted)
• any other ws/ project
• any other domain’s store without the opt-in, and more than one extra domain
• any other domain’s session history (pi-sessions-<other>), also with the opt-in
• any domain configuration store (config/pi-config-<domain>/, read on the host only) and any other domain’s pi-domain-state-<other>

Missing stores#

If a brain repo is missing on the host, the wrapper does three things:

1. It points that store’s source variable at pi-docker-sandbox/empty/, a versioned, empty directory.
2. It mounts that directory with the override compose.missing-<slot>.yaml as read-only.
3. It sets MISSING_STORES=<ids> and prints warning: brain store <id> not found at <path>; starting without it.

The session context marks the store as missing, so the agent does not write there. Nothing is created on the host (Edge Cases). If an opt-in store is missing, it is simply left out, with the same warning.

pi-sandbox selftest uses exactly the session mounts above and checks that /brain holds only core, the session’s domain and the opted-in extra domain. The isolation test is part of the image (/usr/local/lib/pi-sandbox/selftest/), so the self-test adds no mounts.

Sync container mounts (compose.sync.yaml)#

There is no project, no pi-config mount and no agent state. A missing store makes the sync stop with a message. git runs with hooks disabled and without system or global config; the sync refuses a store whose repo-local .git/config has keys outside an allowlist (FR-019a).

Workspace container mounts (compose.workspace.yaml)#

Started only by pi-sandbox workspace clone|refresh (pi-config spec 009, workspace.md). No memory, no pi-config, no configuration store, no agent state, no other domain; the definition check enforces exactly this one bind. Same image and hardening as a session.

Sessions container mounts (compose.sessions.yaml, compose.legacy.yaml)#

Plus tmpfs /tmp and /home/pi. network_mode: none, no bind mount, no project, no memory, no pi-config, no credentials; same hardening as the other containers. Environment: DOMAIN, PI_DOMAINS, SESSION_RETENTION_DAYS.

Check container mounts (compose.check.yaml)#

network_mode: none; no credentials, no git identity, no project, no pi-config, no agent state. Environment: DOMAIN, MISSING_STORES only. Started by pi-sandbox memory-check (pi-config spec 003); scripts/check-sandbox-definition.sh fails if it gets a network or a writable mount.

kube-proxy sidecar (compose.yaml service kube-proxy, profile kube)#

No mounts; tmpfs /tmp (holds the kubeconfig). Same image and hardening as the session container (user 1000, read-only, no capabilities, no-new-privileges), 64 pids, 0.5 CPU, 256 MiB. Environment: PI_KUBECONFIG only. Started by the wrapper per session when a level kube.json provides a kubeconfig, in the session’s own compose project <project>-s<pid>, and removed with its network when the session ends (config.md). kubectl proxy listens on its loopback (8002); kube-filter.py serves port 8001 of that project’s network only (no ports:).

ssh-agent sidecar (compose.ssh.yaml service ssh-agent, profile ssh)#

network_mode: none. Same image and hardening as the session container (user 1000, read-only, no capabilities, no-new-privileges), 32 pids, 0.25 CPU, 64 MiB. Environment: PI_SSH_KEYS only. Started by the wrapper per session when SSH hosts have usable keys, in the session’s own compose project, and removed with the volume when the session ends (config.md). scripts/check-sandbox-definition.sh fails if the volume is not tmpfs or the sidecar gets a network.

Path resolution (FR-017)#

The wrapper resolves <project-path> with realpath, which follows every symlink. The result must lie at $PI_ROOT/ws/<domain>/<path> with at least one folder below the domain; PROJECT is that relative <path> (pi-config spec 004). Rules:

• <domain> is one of the configured domains (PI_DOMAINS, default private work);
• <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. Only the project folder is mounted, at /ws/<domain>/<path>; intermediate folders and sibling projects stay invisible (the selftest checks every level). The container label is pi-sandbox.project=<domain>/<path>; the compose project name is pi-<domain>-<name> for one level and pi-<domain>-<sanitised path, ≤ 40 chars>-<cksum of domain/path> for deeper paths, so same-named projects under different hosts never collide.

Environment variables passed into containers#

Network#

• Default bridge network. Outbound traffic is unrestricted (FR-011). There is no ports: entry.
• The endpoints the agent needs are documented in pi-docker-sandbox/docs/security.md: LLM providers, registry.npmjs.org, gitlab.com and github.com for clones and pulls, and the web search and fetch targets used by pi-web-access.
• Residual risk: the agent can reach LAN and homelab services.