Chapter 18 · Security Model and Environment Variables

Chapter goals: Build a correct认知 of pi's threat model — it "trusts the local user, does not trust repo content"; learn to压 risks to an acceptable range using project trust mechanisms, container isolation, and environment variable management.

18.1 Threat Model: Local Trust Boundary

The official security doc opens with: pi runs with the full权限 of the user who launches it; any file该 user可 write is within the同一 local trust boundary. This implies three typical risks:

1. Prompt injection — READMEs, code comments, build outputs in the repo maycontain "instructions" that the model reads into context and诱导s to execute dangerous operations. Official wording: this is an expected risk of local agents; pi cannot reliably prevent it;
2. Malicious repos — a cloned项目 may带 .pi/settings.json, malicious extensions, or skills that改变 pi's behavior without your知悉;
3. Command execution — the bash tool runs arbitrary commands as your身份; no built-in confirmation弹窗 (Philosophy明确 "No permission popups").

The countermeasures are three layers: project trust (input load闸门) → tool switches (behavior约束) → container isolation (real boundary). The previous chapter covered tool switches (layer 2); this chapter covers layers 1 and 3.

18.2 Project Trust Mechanism (Project Trust)

Project trust decides "whether pi加载 the project's own config and extensions." When pi finds any of the以下 in a project, it认为 the project "contains resources needing trust":

• .pi/settings.json
• .pi/extensions, .pi/skills, .pi/prompts, .pi/themes
• .pi/SYSTEM.md or .pi/APPEND_SYSTEM.md
• Project-level .agents/skills in the current或 ancestor directory

An裸 .pi directory does not count

Only having an空 .pi directory does not trigger a trust确认 — the判定 basis is the具体 resources listed above.

The trust决定 is saved in ~/.pi/agent/trust.json (recorded per-directory); the nearest ancestor directory's decision优先级高于全局默认值. Interactive模式弹出询问;非交互模式 (-p/json/rpc) does notask, falling back to the global defaultProjectTrust:

Value	Non-interactive行为
"ask" (default)	Ignore需信任 project resources
"never"	Ignore需信任 project resources
"always"	Trust and load

Single-run override with -a/--approve force-trust, -na/--no-approve force-ignore:

# In CI trust your own repo's project config (when确认 the repo is trusted)
pi -a -p "Run the project's own checks"

# Audit an陌生 repo: ignore all its project resources + read-only tools
pi -na -t read,grep,find,ls -p "What is this project about?"

Key cognition: trust is just the input load闸门. It prevents the repo from悄悄 changing pi's config and extensions before you批准, but does not make untrusted code, prompt injection, or model output安全.

18.3 No Built-in Sandbox: Isolation Relies on the OS

pi 故意不提供内置沙箱 (confirmed by both Philosophy and security docs). Rationale: an in-process sandbox仍依赖宿主 shell, filesystem,包管理器, credentials, and extension code —容易misinterpreted as a safety boundary. Real隔离 must来自 OS or virtualization boundaries.

For untrusted repos and unattended tasks, the官方给出的 containerization清单 (detailed in Chapter 19):

# Only挂载 the workspace; do not挂载 the host ~/.pi/agent (avoid暴露 sessions and credentials)
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

Key points: only挂载 paths the task needs; pass the minimum API key or use短生命周期凭据; restrict网络 when the task does not need it;审查 the diff before拷回 to the trusted环境. If bind-mounting host dirs读写, writes inside the容器still落 to the host files — use readonly mounts or copy-in/copy-out for stronger保护.

18.4 Storing API Keys and Sensitive Credentials

• Provider凭据放环境变量或 pi's auth file (managed via /login); do not write into shell history or the repo;
• The --api-key arg appears in the process list (ps); only for临时调试;
• Container scenario: inject from the host via -e KEY, or leave the原始 key at the gateway upstream like OpenShell, with the container only accessing https://inference.local.

18.5 Environment Variable Reference

pi's env vars分三类 (official environment-variables.md):

① pi's own config

Variable	Purpose
PI_CODING_AGENT_DIR	Override the config dir (default ~/.pi/agent)
PI_CODING_AGENT_SESSION_DIR	Override session storage dir (--session-dir takespriority)
PI_PACKAGE_DIR	Override the package dir (Nix/Guix scenario)
PI_OFFLINE	Disable启动期 network ops (version check, telemetry)
PI_SKIP_VERSION_CHECK	Skip pi.dev version check
PI_TELEMETRY	0/false/no disable安装/更新 telemetry
PI_CACHE_RETENTION	Set to long toenable extension prompt caching (Anthropic 1h / OpenAI 24h)
HTTP_PROXY / HTTPS_PROXY	Outbound proxy

② Process markers (auto-set by CLI and RPC入口;识别子进程)

Variable	Purpose
AI_AGENT=pi	Generic marker
PI_CODING_AGENT=true	pi-exclusive marker

③ Bash tool session environment (injected into bash commands the modelcalls; note !/!! user commandsdo notinject)

Variable	Purpose
PI_SESSION_ID	Current session ID
PI_SESSION_FILE	Current session JSONL absolute path (unset for ephemeral sessions)
PI_PROVIDER / PI_MODEL	Current model provider / ID
PI_REASONING_LEVEL	Current thinking level

# The model itself can自检 this way instead of guessing the system prompt
printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"

Custom bash tools can close injection via createBashTool()'s exposeSessionEnvironment: false toavoid nested pi processes拿到过期的父会话信息.

18.6 Chapter Summary

• Threat model: trust the local user, do not trust repo content; prompt injection is an expected local risk;
• Project trust只管 "whether to加载 project resources"; the判定 objects are specific resources under .pi/ and project-level .agents/skills;
• Non-interactive mode靠 defaultProjectTrust or -a/-na single-run override;
• No内置 sandbox is a设计决定: real isolation via containers/micro VMs; only挂载 the workspace, minimum credentials, on-demand network restriction;
• Env vars三类: pi config (PI_OFFLINE etc.), process markers (AI_AGENT), bash session env (PI_SESSION_ID etc.).

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Which of the following does NOTtrigger project trust confirmation?

2. In non-interactive mode when defaultProjectTrust取 the default value "ask", project resources are?

3. Why does the official不建议 replacing container isolation with an in-process sandbox?

4. Regarding bash tool session env vars, which statement is correct?

🛠️ Hands-on Practice

1. In a test repo create .pi/SYSTEM.md;start pi in interactive mode, -p mode, and -na -p mode respectively;observe whether the file is loaded in三种模式.
2. Run pi in a Docker container: only挂载 the workspace; use a named volume for ~/.pi/agent; verify the container cannot read the host sessions.
3. Write a script printing the bash tool session env: have pi run env | grep ^PI_;对照 the doc核对 each var's value and meaning.