Secrets and credentials (names only)
pi-config contains no secrets and never needs any: pi’s credentials and state live in the
sandbox’s pi-agent-state volume or are injected at runtime by pi-docker-sandbox. The
template that lists every local setting is
pi-docker-sandbox/.env.example (spec FR-014).
| Name | Kind | Where it lives | Used by |
|---|---|---|---|
Stored login (auth.json) | Model credential | pi-agent-state volume | pi, default method |
pi-sandbox / anthropic-api-key | Model API key | macOS Keychain | pi, only with pi-sandbox start --key-from-keychain, as ANTHROPIC_API_KEY |
pi-sandbox / brain-core-token, brain-<domain>-token (e.g. brain-private-token, brain-work-token) | Memory push credentials (user:token); one per configured domain, or a BRAIN_<ID>_TOKEN_CMD in .env instead | macOS Keychain | Only the separate memory sync container |
BRAIN_CORE_URL, BRAIN_<ID>_URL (e.g. BRAIN_PRIVATE_URL, BRAIN_WORK_URL) | Push URLs (not secret) | pi-docker-sandbox/.env | Memory sync |
pi-sandbox / mcp-<domain>-<NAME> | Secret for an MCP placeholder ${NAME} (pi-config spec 007); or MCP_<ID>_<NAME>_CMD in .env | macOS Keychain | Only the session whose merged MCP configuration uses ${NAME}, as PI_MCP_SECRET_<n> |
FIGMA_API_KEY_CMD (.env) | Figma personal access token (read-only scopes), printed by a host command such as op read …; the session gets the token as environment variable FIGMA_API_KEY; no Keychain item | pi-docker-sandbox/.env holds the command only | Every session (the variable is empty without the command), read by the figma MCP server |
GIT_AUTHOR_*, GIT_COMMITTER_* | Git identity (personal, not secret) | pi-docker-sandbox/.env | Local commits in the sandbox |
<ID> is the domain name in uppercase with - → _ (my-club → BRAIN_MY_CLUB_URL); the
domains are PI_DOMAINS in pi-docker-sandbox/.env (pi-docker-sandbox docs/commands.md).
Every Keychain item above can instead come from a password manager: set the matching
*_CMD in pi-docker-sandbox/.env (ANTHROPIC_API_KEY_CMD, BRAIN_CORE_TOKEN_CMD,
BRAIN_PRIVATE_TOKEN_CMD, BRAIN_WORK_TOKEN_CMD) to a command such as op read op://… or
bw get password …. The variable holds the reference, never the secret; usernames for bare
memory tokens go to BRAIN_<STORE>_USER.
Credentials for MCP servers or packages, if ever needed, follow the same rules: named in
.env.example and here, injected at runtime, and referenced in agent/ config by env-var name
only — never as values.
How to revoke and replace each credential:
pi-docker-sandbox/docs/credentials.md.
.gitignore additionally ignores pi’s runtime files (auth.json, trust.json, sessions/,
npm/, git/, mcp-cache*.json, bin/, node_modules/, .env*) as defence in depth.
Telegram bridge (optional)#
TELEGRAM_BOT_TOKEN: the bot token for npm:@llblab/pi-telegram (from @BotFather; revoke with
/revoke), injected by pi-docker-sandbox from TELEGRAM_BOT_TOKEN_CMD. ~/.pi/agent/telegram.json
holds only the reference $TELEGRAM_BOT_TOKEN when set up through /telegram-setup. See
config-reference.md.