沙盒化

The runtime can wrap tool invocations in an OS-level sandbox that restricts filesystem access to the workspace and removes access to the parent process’s secrets. This is distinct from the autonomy system and command allow-list: those are policy layers that decide whether a tool may run; the sandbox is a mechanism layer that confines what a running tool can reach if it does run.

Sandbox settings live on a risk profile. Each agent points at a risk profile via agents.<alias>.risk_profile; the agent’s sandbox enable/backend are read from that profile.

[risk_profiles.assistant]
sandbox_enabled = true
sandbox_backend = "auto"     # "auto" | "landlock" | "firejail" | "bubblewrap" | "docker" | "sandbox-exec" | "none"
firejail_args   = []          # extra args when sandbox_backend = "firejail"

sandbox_enabled = false (or sandbox_backend = "none") disables sandboxing for tools running under this profile. See the canonical Minimal working example for how a risk profile slots into the rest of the config.

自动检测

sandbox_backend = "auto" picks the best available backend at startup:

To force a specific backend, set sandbox_backend to one of the literal values listed above.

沙箱所限制的内容

文件系统

• Read access — restricted to the workspace, /usr, /lib, /etc (read-only), and explicitly-listed extra paths.
• Write access — restricted to the workspace and /tmp.
• Forbidden paths — anything listed in [risk_profiles.<alias>].forbidden_paths.

网络

By default, sandboxed tools have full network egress but no inbound listening. Per-backend caveats:

• Landlock does not control network — it is filesystem-only.
• Bubblewrap and Firejail can block network when configured.
• Docker container network mode follows [runtime.docker].network when [runtime].kind = "docker".

Tool-specific network gates (browser, HTTP, web_fetch) live on those tools’ own config blocks ([browser].allowed_domains, [http_request].allowed_domains, [web_fetch].allowed_domains).

环境

The sandbox passes through only the env vars listed in [risk_profiles.<alias>].shell_env_passthrough. Inherited secrets do not reach sandboxed tools unless explicitly passed.

进程限制

Per-tool wall-time timeouts live on the tool’s own config block ([shell_tool].timeout_secs, etc.). Docker-specific limits (memory, CPU) live on [runtime.docker] when the agent’s runtime kind is set to docker:

[runtime]
kind = "docker"

[runtime.docker]
image            = "alpine:3.20"
network          = "none"
memory_limit_mb  = 512
cpu_limit        = 1.0
read_only_rootfs = true
mount_workspace  = true

各后端的说明

Landlock

Linux 原生路径。零配置，内核强制实施，开销极低。需要内核 5.13 或更高版本。

限制：

• No network confinement — Landlock only controls filesystem access.
• forbidden_paths is enforced via path-based rules, not inode-based, so a clever symlink can sometimes escape (we resolve links before handing to Landlock to mitigate this).

Bubblewrap (bwrap)

User-namespace-based sandbox from Flatpak. Confines filesystem and can block network. Requires bubblewrap installed.

sudo apt install bubblewrap       # Debian/Ubuntu
sudo pacman -S bubblewrap         # Arch
sudo dnf install bubblewrap       # Fedora

Firejail

基于 SUID 的沙箱。较旧但广泛可用。

sudo apt install firejail

Firejail’s default profile is fairly permissive; ZeroClaw applies a custom profile. Pass extra args with firejail_args on the risk profile.

Docker

Works anywhere Docker does. The Docker runtime kind ([runtime] kind = "docker") runs each shell invocation in an ephemeral container; see the [runtime.docker] block above for image and resource controls.

docker build -t zeroclaw-sandbox:local dev/sandbox/   # build the bundled toolkit image

[runtime]
kind = "docker"

[runtime.docker]
image = "zeroclaw-sandbox:local"

优点：隔离性强，适用于任何操作系统。缺点：每次调用时容器启动开销较大（100–500 毫秒）。最适合对开销可接受的生产环境部署。

安全带 (macOS)

Native macOS sandbox (sandbox-exec). Profiles are SBPL — ZeroClaw bundles one for tool runs. Works on macOS 10.11+.

Limitation: some CLI tools (older git, some Homebrew-linked binaries) don’t cooperate with Seatbelt’s file-access rules. If you see “Operation not permitted” errors from the agent’s shell calls on macOS, the tool needs broader filesystem access — consider switching to Docker.

none

无沙盒机制。工具以 ZeroClaw 服务用户的完整权限运行。这正是 YOLO 模式所启用的特性。明确、显著且有意为之。

故障排除

• 启动时出现 “Sandbox backend unavailable”（沙箱后端不可用）——请检查 zeroclaw service status 和系统日志；自动检测日志会记录它尝试过哪些后端。
• 在开发环境中正常、在服务环境中失败的工具——服务用户通常与 CLI 用户不同。请验证两者都具备所需的沙箱相关权限（Landlock：无；Bubblewrap：启用用户命名空间；Docker：将服务用户加入 docker 组）。
• Slow tool invocations on the Docker runtime — first invocation pulls the image, subsequent are fast. Pre-pull with docker pull <image>.

代码参考

• 检测：crates/zeroclaw-runtime/src/security/detect.rs
• 后端：crates/zeroclaw-runtime/src/security/sandbox/（每个后端一个文件）
• Schema: RiskProfileConfig and DockerRuntimeConfig in crates/zeroclaw-config/src/schema.rs