Pi Agent: Security & Project Trust
Last updated: 2026-08-31
An Agent can execute commands for you — or cause damage. Security mechanisms are the "brakes."
1. Security Model Overview
Pi Agent's security is based on a three-layer model:
TEXT
📖 Display only
Security Three-Layer Model
├── Layer 1: Project Trust — Whether the Agent can access the project
├── Layer 2: Tool Permission — Which tools are allowed
└── Layer 3: Execution Sandbox — Security boundary for tool execution
2. Project Trust
(1) Trust Levels
| Level | Description | Allowed Operations |
|---|---|---|
| untrusted | No trust | Chat only, no file/command access |
| readonly | Read-only | Read project files, no modifications |
| trusted | Full trust | Read/write files, execute commands |
| restricted | Restricted | Custom whitelist operations |
(2) Setting Trust Level
BASH
pi-agent trust set ./my-project --level trusted
pi-agent trust list
(3) First-Interaction Prompt
When using Pi Agent in a new project directory:
TEXT
📖 Display only
New project detected: /home/alice/my-project
Trust this project? [y/N]
trusted - Full access (read/write files, execute commands)
readonly - Read-only access
untrusted - No access
Select trust level:
(4) Python API
PYTHON
from pi_agent import Agent, TrustLevel
agent = Agent(
name="safe_agent",
project_path="./my-project",
trust_level=TrustLevel.READONLY
)
3. Tool Permissions
(1) Danger Levels
| Level | Example Tools | Default State |
|---|---|---|
| Safe | calculator, search | Auto-enabled |
| Medium | file_reader | Requires confirmation |
| Dangerous | file_write, shell | Requires explicit authorization |
(2) Permission Config
YAML
permissions:
tools:
safe: auto
medium: confirm
dangerous: deny
allow:
- calculator
- search
- file_reader
deny:
- shell
- file_write
confirm_dangerous: true
confirm_file_write: true
confirm_shell: true
(3) Runtime Confirmation
TEXT
📖 Display only
you> Delete all temporary files
Agent wants to execute: rm -rf /tmp/project_*
Allow? [y/N/a(always)]
4. Execution Sandbox
PYTHON
from pi_agent import Agent
agent = Agent(
name="sandboxed",
sandbox=True,
sandbox_dir="/tmp/pi_sandbox",
allowed_commands=["python", "pytest"],
max_execution_time=30
)
File system isolation:
PYTHON
agent = Agent(
sandbox=True,
sandbox_dir="./workspace/sandbox",
allowed_paths=["./data/", "./output/"]
)
Network restrictions:
PYTHON
agent = Agent(
sandbox=True,
network_access=False,
allowed_domains=["api.github.com"]
)
5. Best Security Practices
- API keys in env vars, not config files
- Add
.pi-agent.local.yamlto.gitignore - Least privilege: only grant necessary permissions
- Enable audit logging
PYTHON
agent = Agent(
audit_log=True,
audit_file="./audit.log"
)
FAQ
Q Can trust be revoked?
A Yes.
pi-agent trust set ./project --level untrusted or delete the file in ~/.pi-agent/trust/.Q Can shell tool be completely disabled?
A Yes. Add
deny: [shell] in config or don't include it in the tools list. This is recommended.Q Does sandboxing affect performance?
A File system isolation has negligible impact. Network restrictions may affect tools that need internet.
Summary
- Three-layer security: project trust → tool permissions → execution sandbox
- Four trust levels: untrusted, readonly, trusted, restricted
- Tools classified by danger: safe (auto), medium (confirm), dangerous (deny)
- Sandbox isolates filesystem, restricts network, controls execution time
- API keys via env vars, least privilege, enable audit logs
Exercises
- Basic (Difficulty: ⭐): Set readonly trust for your project, observe Agent behavior in restricted mode.
- Intermediate (Difficulty: ⭐⭐): Configure a sandboxed Agent that only reads specific directories and runs Python commands.
- Advanced (Difficulty: ⭐⭐⭐): Write a security policy file with a complete permission matrix, verify via audit logs.
