Pi는 로컬 에이전트의 정직함을 전제로 설계됩니다. 모델이 만든 명령과 코드는 신뢰할 수 없는 입력으로 다뤄야 합니다. Pi는 실행 계정 권한으로 파일을 읽고, 고치고, 실행할 수 있으며, 매 도구 호출마다 승인을 요구하지 않습니다. 확장, 패키지 설치기, 언어 서버 등 자식 프로세스도 같은 권한으로 동작합니다.

파일, 주석, 지침, 명령 출력, 모델 응답은 모두 프롬프트 인젝션으로 모델을 조종할 수 있는 경로입니다. 프로젝트 신뢰는 시작 시 로드할 프로젝트 자원을 통제할 뿐, 그 내용과 그로 인한 동작까지 안전하게 만들지는 않습니다. 안전은 "잘못되거나 악의적인 생성 동작이 접근할 수 있는 파일·자격 증명·프로세스·네트워크를 제한하는 것"에서 나옵니다. 대화 기록을 지켜보고, 프로젝트 신뢰를 쓰고, diff를 검토하는 것만으로는 보안 경계가 만들어지지 않습니다.

실행 방식별 보호 범위

실행 방식	보호되는 것
운영체제 사용자 권한으로 직접 실행	그 사용자가 접근할 수 없는 것들. 전용 계정 권한 축소가 도움은 되지만 OS와 네트워크는 여전히 공유
컨테이너·VM·샌드박스 전체에서 실행	노출하지 않는 호스트 파일·프로세스. 보통 실효성 있는 최선의 선택
Pi는 밖, 내장 도구만 안에서 실행	그 도구들을 통한 동작으로부터 호스트 자원 보호. Pi 자체와 다른 확장은 경계 밖에 남는 좁은 격리

작업 폴더는 자원 탐색과 기본 도구 위치를 결정할 뿐, 프로세스에 허용된 다른 경로 접근까지 막지는 못합니다. 어떤 방식을 택하든 작업에 필요한 파일과 서비스만 제공하고, 자격 증명은 가급적 환경 밖에 두거나 좁은 범위의 단기 자격 증명을 쓰며, 불필요한 네트워크 접근은 차단하세요.

프로젝트 신뢰가 통제하는 것

프로젝트 신뢰는 작업 폴더가 제공하는 설정과 자원 대다수를 로드할지 여부입니다. 신뢰 없이 실행되면 승인하지 않은 폴더가 실행 가능한 확장을 몰래 로드하는 것을 막을 수 있습니다.

신뢰 판정을 요구하는 자원:

• .pi/settings.json, .pi/mcp.json
• .pi/extensions, .pi/skills, .pi/prompts, .pi/themes
• .pi/SYSTEM.md, .pi/APPEND_SYSTEM.md
• 현재 폴더 또는 조상의 프로젝트 .agents/skills

빈 .pi 디렉터리만으로는 신뢰 판정을 요구하지 않습니다. 신뢰를 허용하면 프로젝트 설정, MCP 서버, .pi 아래 확장·스킬·템플릿·테마·시스템 프롬프트 파일, 프로젝트 설정이 지정한 패키지 등이 로드됩니다.

한계도 분명합니다.

• AGENTS.md, CLAUDE.md 같은 컨텍스트 파일은 신뢰 여부(또는 컨텍스트 로드 자체를 끄지 않는 한)와 무관하게 로드됩니다. 폴더 안의 지침은 신뢰를 거부해도 신뢰할 수 없는 입력으로 취급하세요.
• 신뢰 판정은 도구 호출이 접근·수정할 수 있는 범위를 제한하지 않습니다. Pi가 뜬 뒤에는 활성화된 도구가 프로세스의 OS 권한을 그대로 씁니다.
• 유일한 예외로, 프로젝트 sessionDir 설정은 세션 선택을 위해 신뢰 판정 전에 읽힙니다.

신뢰 판정 순서

CLI의 --approve/--no-approve가 최우선이고, 보호된 자원이 있는데 명령행 덮어쓰기가 없으면 다음 순서로 결정됩니다.

1. 사용자·CLI 확장이 project_trust 이벤트를 처리 (첫 번째로 예/아니오를 답한 확장 결정)
2. 현재 또는 조상 폴더에 저장된 판정 (가장 가까운 것이 적용, ~/.pi/agent/trust.json에 저장)
3. 전역 defaultProjectTrust 설정 (기본 "ask")

/trust로 미래 프로세스에 적용될 판정을 저장합니다. print·JSON·RPC 모드는 신뢰 프롬프트를 띄울 수 없으므로, 명령행 덮어쓰기·확장·저장된 판정이 없으면 defaultProjectTrust가 "always"일 때만 보호 자원을 로드하고 "ask"/"never"에서는 건너뜁니다. 무인 실행에는 --approve/--no-approve로 일회성 판정을 명시하세요.

격리 실행 패턴

공식 문서(Containerization)는 세 가지 패턴을 안내합니다.

• Gondolin 확장: pi와 제공자 인증은 호스트에 두고, 내장 도구와 ! 명령만 로컬 Linux micro-VM에서 실행
• 일반 Docker: pi 프로세스 전체를 로컬 컨테이너에서 실행해 단순 격리
• OpenShell: 정책 제어 샌드박스에서 전체 프로세스 실행

실전 안전 수칙

격리를 대체하지는 않지만 노출을 줄이고 복구를 쉽게 하는 습관들입니다.

• 작업에 필요한 파일과 서비스만 접근 허용
• 큰 변경 전에 스냅샷·백업·버전 관리
• 확장과 패키지는 로드 전 검토 (확장은 Pi 프로세스 안에서 실행됨)
• 좁은 범위·단기 자격 증명 선호
• 결과물을 다른 시스템에 적용하기 전 diff와 생성물 검토
• 세션 내보내기·공유 전 검토 (프롬프트, 도구 인자, 명령 출력, 파일 내용, 노출된 자격 증명이 들어 있을 수 있음)

보안 문제는 저장소의 Security Policy에 따라 비공개로 신고합니다. 로컬 에이전트의 기대 동작, 신뢰할 수 없는 콘텐츠로부터의 프롬프트 인젝션, 내장 샌드박스의 부재, 사용자가 설치한 확장·스킬의 동작은 권한 경계 우회 증명이 없는 한 보통 보안 경계 밖으로 봅니다.