● Overview 개요

Sandboxed Bash replaces the standard root-session bash tool with a sandboxed execution layer. Every shell command passes through a policy engine and a platform-specific isolation adapter before reaching the host. If no sandbox tool is available on the current platform, the system falls back to unsandboxed execution with explicit user approval.

샌드박스 Bash는 표준 root-session bash 도구를 샌드박스 실행 레이어로 교체합니다. 모든 셸 명령은 호스트에 도달하기 전에 정책 엔진과 플랫폼별 격리 어댑터를 거칩니다. 현재 플랫폼에 샌드박스 도구가 없으면, 명시적인 사용자 승인과 함께 샌드박스 없는 실행으로 폴백합니다.

▶ How It Works 작동 원리

Root sessions register a tool labeled "bash (sandboxed)". When the agent issues a bash command, the execution pipeline is:

Root 세션은 "bash (sandboxed)"라는 레이블의 도구를 등록합니다. 에이전트가 bash 명령을 발행하면 실행 파이프라인은 다음과 같습니다:

Command → Policy Engine → Platform Adapter (bwrap | sandbox-exec) → Execution명령 → 정책 엔진 → 플랫폼 어댑터 (bwrap | sandbox-exec) → 실행

Bash is launched as:

Bash는 다음과 같이 실행됩니다:

bash -lc <command>

The policy engine evaluates platform capability, filesystem mode, and network mode to produce a sandbox decision. If the decision is sandboxed, the platform adapter wraps the command in the appropriate isolation mechanism. If the decision is unsandboxed, the approval flow determines whether execution is permitted.

정책 엔진은 플랫폼 기능, 파일시스템 모드, 네트워크 모드를 평가하여 샌드박스 결정을 내립니다. 결정이 sandboxed이면 플랫폼 어댑터가 명령을 적절한 격리 메커니즘으로 감쌉니다. 결정이 unsandboxed이면 승인 흐름이 실행 허용 여부를 결정합니다.

■ Platform Adapters 플랫폼 어댑터

Each platform has a dedicated adapter that provides sandbox capability detection and launch construction:

각 플랫폼에는 샌드박스 기능 감지 및 실행 구성을 제공하는 전용 어댑터가 있습니다:

★ Linux (bwrap) Linux (bwrap)

The Linux adapter uses bubblewrap for namespace-level isolation. The full launch command:

Linux 어댑터는 네임스페이스 수준 격리를 위해 bubblewrap을 사용합니다. 전체 실행 명령:

bwrap \
  --die-with-parent \
  --new-session \
  --ro-bind / / \
  --proc /proc \
  --dev /dev \
  --tmpfs /tmp \
  --bind <workspace> <workspace> \
  --chdir <cwd> \
  [--unshare-net] \
  -- <command>

Flags explained:

플래그 설명:

• --die-with-parent — Kill the sandbox if the parent process dies. 부모 프로세스가 종료되면 샌드박스를 종료합니다.
• --new-session — Create a new process session. 새 프로세스 세션을 생성합니다.
• --ro-bind / / — Mount the root filesystem read-only. 루트 파일시스템을 읽기 전용으로 마운트합니다.
• --proc /proc — Mount a new proc filesystem. 새 proc 파일시스템을 마운트합니다.
• --dev /dev — Mount a minimal /dev. 최소한의 /dev를 마운트합니다.
• --tmpfs /tmp — Mount a fresh tmpfs at /tmp. /tmp에 새 tmpfs를 마운트합니다.
• --bind <workspace> <workspace> — Bind-mount the workspace read-write. 워크스페이스를 읽기-쓰기로 바인드 마운트합니다.
• --chdir <cwd> — Set working directory inside the sandbox. 샌드박스 내 작업 디렉토리를 설정합니다.
• --unshare-net — Disable network access (when network mode is "off"). 네트워크 액세스 비활성화 (네트워크 모드가 "off"일 때).

◆ macOS (sandbox-exec) macOS (sandbox-exec)

The macOS adapter uses Apple's sandbox-exec with a dynamically generated SBPL profile. The profile is written to a temporary file and cleaned up after execution:

macOS 어댑터는 동적으로 생성된 SBPL 프로필과 함께 Apple의 sandbox-exec를 사용합니다. 프로필은 임시 파일에 기록되고 실행 후 정리됩니다:

(version 1)
(deny default)
(import "system.sb")
(allow process*)
(allow sysctl-read)
(allow file-read*)
(allow file-write*
  (subpath "<workspace>")
  (subpath "/tmp")
  (subpath "<tmpdir>"))
(allow network*) # when network mode is "on"

Profile explained:

프로필 설명:

• (deny default) — Deny all operations by default. 기본적으로 모든 작업을 거부합니다.
• (import "system.sb") — Import macOS system sandbox defaults. macOS 시스템 샌드박스 기본값을 임포트합니다.
• (allow process*) — Allow process creation and signal operations. 프로세스 생성 및 시그널 작업을 허용합니다.
• (allow sysctl-read) — Allow reading system information. 시스템 정보 읽기를 허용합니다.
• (allow file-read*) — Allow reading any file. 모든 파일 읽기를 허용합니다.
• (allow file-write* ...) — Restrict writes to workspace, /tmp, and the system tmpdir. 쓰기를 워크스페이스, /tmp, 시스템 tmpdir로 제한합니다.
• (allow network*) — Enable network access (only when network mode is "on"). 네트워크 액세스 활성화 (네트워크 모드가 "on"일 때만).

● Approval Flow 승인 흐름

When sandbox capability is unavailable or the policy engine decides unsandboxed execution is needed, the approval flow gates command execution. The mode is controlled via the PI_SANDBOX_APPROVAL_MODE environment variable:

샌드박스 기능을 사용할 수 없거나 정책 엔진이 샌드박스 없는 실행이 필요하다고 결정할 때, 승인 흐름이 명령 실행을 제어합니다. 모드는 PI_SANDBOX_APPROVAL_MODE 환경 변수로 제어됩니다:

Approval choices presented to the user:

사용자에게 제시되는 승인 선택:

• Deny — Block this command. 거부 — 이 명령을 차단합니다.
• Allow once — Execute this command once, no caching. 한 번 허용 — 이 명령을 한 번 실행, 캐싱 없음.
• Allow for session — Cache approval for the session (6-hour TTL, persisted). 세션 동안 허용 — 세션 동안 승인 캐시 (6시간 TTL, 영구 저장).
• Always allow — Persist approval indefinitely. 항상 허용 — 승인을 무기한 영구 저장.

Approval scopes:

승인 범위:

• once — Single execution, no persistence. 단일 실행, 영속성 없음.
• session — Cached for the session with a configurable TTL (default 6 hours, PI_SANDBOX_SESSION_APPROVAL_TTL_MS). 구성 가능한 TTL로 세션 동안 캐시됨 (기본 6시간, PI_SANDBOX_SESSION_APPROVAL_TTL_MS).
• always — Persisted to disk and never expires. 디스크에 영구 저장되며 만료되지 않음.

Approvals are persisted to ~/.pi/agent/sandbox-approvals.json using a versioned format (v2) that supports both scope types and expiration timestamps.

승인은 두 범위 유형과 만료 타임스탬프를 모두 지원하는 버전 관리 형식(v2)을 사용하여 ~/.pi/agent/sandbox-approvals.json에 영구 저장됩니다.

▶ Sensitive Environment Detection 민감한 환경 변수 감지

The sandbox system detects files that may contain sensitive environment variables. A file is flagged as sensitive if its basename matches .env or starts with .env. (e.g., .env.local, .env.production).

샌드박스 시스템은 민감한 환경 변수를 포함할 수 있는 파일을 감지합니다. 파일의 베이스네임이 .env와 일치하거나 .env.로 시작하면(예: .env.local, .env.production) 민감한 것으로 표시됩니다.

■ Configuration 설정

★ Edge Cases 엣지 케이스

No Sandbox Tool Available 샌드박스 도구 없음

If neither bwrap nor sandbox-exec is present (or the platform is unsupported), the system falls back to unsandboxed execution. The approval prompt is presented to the user unless PI_SANDBOX_APPROVAL_MODE=always or =deny overrides it.

bwrap이나 sandbox-exec이 없거나 플랫폼이 지원되지 않는 경우, 시스템은 샌드박스 없는 실행으로 폴백합니다. PI_SANDBOX_APPROVAL_MODE=always 또는 =deny가 재정의하지 않는 한 사용자에게 승인 프롬프트가 표시됩니다.

Writable Roots 쓰기 가능 루트

In addition to the workspace root, the sandbox allows writes to the Pi agent directory and session directory. These are resolved from PI_CODING_AGENT_DIR and PI_CODING_AGENT_SESSION_DIR (defaulting to ~/.pi/agent and the session temp dir respectively).

워크스페이스 루트 외에도 샌드박스는 Pi 에이전트 디렉토리와 세션 디렉토리에 쓰기를 허용합니다. 이들은 PI_CODING_AGENT_DIR과 PI_CODING_AGENT_SESSION_DIR에서 해결됩니다 (기본값은 각각 ~/.pi/agent와 세션 임시 디렉토리).

Network Mode 네트워크 모드

Network access is configurable per execution. When set to "off", Linux uses --unshare-net and macOS omits the (allow network*) clause from the SBPL profile. When set to "on", full network access is permitted within the sandbox.

네트워크 액세스는 실행마다 구성할 수 있습니다. "off"로 설정하면 Linux는 --unshare-net을 사용하고 macOS는 SBPL 프로필에서 (allow network*) 절을 생략합니다. "on"으로 설정하면 샌드박스 내에서 전체 네트워크 액세스가 허용됩니다.