pi-config

The versioned, secret-free agent configuration for my pi coding agent. pi runs only inside the sandbox container defined in pi-docker-sandbox. This repo holds only what pi loads as configuration.

Layout#

Everything lives side by side under ~/pi/ (PI_ROOT):

Area	Location	Purpose	Lifecycle	Mount in the sandbox
Config	`pi-config/` (this repo)	Global instructions, settings, pinned packages, skills, prompts	Versioned in git; changes apply on the next session start	`agent/` only, read-only at `/opt/pi-config/agent`
Brain	`brain/pi-memory-core`, `brain/pi-memory-<domain>`	Persistent agent memory, one git repo per store	Written by the agent; pushed only by the owner-started memory sync	core and the project’s domain read-write; one other domain read-only, and only with `--with-domain <name>`
Agent state	Docker volumes `pi-agent-state` (login, packages, trust — shared) and `pi-sessions-<domain>` (session history, one per domain, kept 30 days by default)	pi’s runtime state, never in git	Written by pi in the sandbox; old sessions pruned on every start	`pi-agent-state` at `/home/pi`, only the session’s own `pi-sessions-<domain>` over `~/.pi/agent/sessions`
Context configuration	`config/pi-config-<domain>/<path>/{settings.json,mcp.json}` (one git repo per domain)	Settings and MCP servers per domain, host, customer, project; override `agent/` (pi-config spec 007)	Maintained and pushed by the owner; read and merged on the host at each start	Never mounted: the session gets only the merged result
Workspace	`ws/<domain>/<path>` (any depth)	Project checkouts the agent works on	Cloned and pushed by the owner on the host; `ws/` itself is not a git repo	Only the selected project, read-write, at `/ws/<domain>/<path>`
Sandbox	`pi-docker-sandbox/`	Container definition, `pi-sandbox` command, sandbox docs	Versioned in git; image rebuilt on version bumps	Not mounted

The default domains are private (personal and homelab projects) and work (work and customer projects); more are added with pi-sandbox domain add <name> (they live in PI_DOMAINS in pi-docker-sandbox/.env, not in this repo). core is memory shared by all domains.

The full host ↔ container mapping is in pi-docker-sandbox/docs/path-contract.md.

What is in this repo#

text
agent/                  everything pi loads — mounted read-only at /opt/pi-config/agent
├── AGENTS.md           global instructions (sandbox facts, git rules, working style, memory rules)
├── settings.json       model defaults, resource paths, pinned packages (global level)
├── mcp.json            global MCP servers (global level; spec 007)
├── npmrc               npm allow-list for the packages' install scripts
├── skills/             skills (herdr, terraform-skill, workspace-clone)
└── prompts/            prompt templates (memory-seed)
docs/
├── config-reference.md every agent/ item and settings key: what, why, default
├── migration.md        keep/drop review of the old host setup
└── secrets.md          names of every credential (no values; this repo holds none)
scripts/check-docs.sh   fails on any undocumented agent/ item
scripts/check-npm-supply-chain.sh  npm signatures + install-script allow-list (PR check)
scripts/ci-install-tools.sh  pinned check tools for CI
scripts/update-ci-checksums.sh  rewrites the CI tool checksums (Renovate post-upgrade)
renovate.json           dependency updates by Renovate (docs/dependencies.md)
.forgejo/workflows/renovate.yml  scoped Renovate run for this repo
.forgejo/workflows/      release pipeline (just check, then semantic-release)
.releaserc.json, package.json  semantic-release config and pinned tooling (not an npm package)
CHANGELOG.md            written by semantic-release
tests/                  bats tests for the docs check
justfile                `just check`
specs/, .specify/       Spec Kit specs, plan and constitution

How the config is loaded#

pi never reads this repo directly. On every session start the sandbox merges agent/settings.json and agent/mcp.json (the global level) with the session domain’s configuration store (config/pi-config-<domain>/, pi-config spec 007), gives pi the result as session-local files, stacks agent/AGENTS.md with the store’s AGENTS.md files of each level (nearest last) and adds the store’s skills and prompt templates (nearest wins; spec 008), copies agent/npmrc as npm config and installs the pinned packages (details). Runtime changes pi makes to its settings or MCP servers are discarded when the session ends, so this repo (and the configuration stores) stay the single source of truth.

Changing the config#

Edit agent/… and document the change in docs/config-reference.md in the same commit.
Run just check (docs coverage + secret scan).
Restart the session: pi-sandbox start ~/pi/ws/<domain>/<path>.

To add a package, pin it exactly (npm:<name>@<x.y.z>), say where it comes from and why, and remember it runs with the agent’s full access in the container.

Running pi#

See pi-docker-sandbox: pi-sandbox start, stop, shell, rebuild. pi is never run on the host with this config.

Releases#

Every push to main runs just check and semantic-release on the self-hosted Forgejo runner: version from Conventional Commits, CHANGELOG.md, tag v<version>, Codeberg release. Details: docs/release.md.

Dependency updates#

Renovate opens pull requests for the pi packages, release tooling, CI tools and actions: docs/dependencies.md.

In this part

Levels and merging: Layered settings, MCP servers, instructions, skills and prompt templates
Reference: Config reference
Secrets: Secrets and credentials (names only)
Migration review: Migration review of the host pi setup (spec FR-015)