EN 中文

# OS Sandbox — Kernel-Level Security

# OS 沙箱 — 内核级安全边界

Kernel-level jail for unattended subprocesses — no Docker, no container runtime, zero extra deps.

为无人值守子进程提供内核级 jail——不依赖 Docker，零额外依赖。

Supported platforms: macOS Seatbelt and Linux Landlock. Unsupported platforms (Windows, BSD) silently degrade to worktree-level logical isolation.

当前支持 macOS Seatbelt 和 Linux Landlock。不支持的平台静默降级为 worktree 逻辑隔离。

## What It Confines

## 它能做什么

Operation | 操作 | macOS (Seatbelt) | Linux (Landlock)
--- | --- | --- | ---
File read | 文件读 | ✅ Allow all | ✅ Allow all
File write | 文件写 | ✅ Whitelist dirs only | ✅ Whitelist dirs only
Network | 网络 | ✅ Default blocked, can allow | ❌ Landlock doesn't manage net
exec | 执行 | ✅ Allowed (sandbox-exec restricted) | ✅ Allowed
Kernel requirement | 内核要求 | Built-in (needs sandbox-exec) | Linux ≥ 5.13 (Landlock ABI ≥ 1)

### macOS Seatbelt

### macOS

- Uses `sandbox-exec` (marked deprecated but fully functional, zero cgo)
- 使用 sandbox-exec（虽标记为 deprecated 但功能完好，零 cgo）
- Network blocked by default, opt-in via `AllowNetwork`
- 网络默认禁止，通过 AllowNetwork 放行
- Policy written in SBPL (Seatbelt Profile Language)
- 用 SBPL 生成策略

### Linux Landlock

### Linux

- Linux kernel LSM, available since 5.13
- Linux 内核 LSM，从 5.13 开始可用
- Auto-detects ABI version and downgrades unsupported rights (REFER → ABI 2, TRUNCATE → ABI 3, IOCTL_DEV → ABI 5)
- 自动探测 ABI 版本并降级不支持的权限
- Re-exec trampoline: process execs itself → applies landlock → execs target command. Fail-closed — if jail creation fails, process exits without executing.
- 通过 re-exec trampoline 实现，fail-closed——如果 jail 创建失败，进程退出而不执行命令
- Requires `no_new_privs` (trampoline sets it automatically)
- 需要 no_new_privs（trampoline 自动设置）
- Network is NOT managed by Landlock (by design)
- 网络不管——Landlock 不管理网络

## How to Enable

## 如何启用

The sandbox is auto-detected and integrated into autopilot sub-agents:

沙箱默认集成在 autopilot 子代理中，自动检测可用性：

    // Auto-detected in autopilot mode
    if sandbox.Available() {
        bt = bt.WithSandbox(sandbox.Options{
            WritableDirs: []string{worktreePath},
        })
    }

When unavailable, subprocesses run without kernel confinement but still within worktree isolation.

不可用时，子进程运行在 worktree 隔离中，没有内核约束。

## Design Docs

## 设计文档

PRD feature-sandbox.md

PRD feature-sandbox.md