智能体沙箱 delta-box/deltabox-lite

轻量、面向智能体的沙箱，支持 diff · commit · abort。

给智能体一个受限工作区，并提供明确的 diff、commit、abort 语义。

deltabox-lite 是独立的沙箱运行时，面向 AI 编程智能体。智能体在受限的文件系统视图里保留完整的执行自由，它做的每一处改动都可以审阅、提交或中止——按任务或按工具调用。Linux 默认使用偏向提交的 FUSE 视图；macOS 使用原生 APFS 克隆和 FSEvents；Windows 使用 WinFsp 视图。私有模式会把改动对宿主机隐藏，直到提交为止。

可以把它想成智能体会话的 Git：仪式更少，控制更多，也不必为二进制文件或大文件焦虑。

📰 动态

- [2026/10/25] DSH v0.1.5：支持 DSH v0.2.2

- [2026/10/21] 发布 v0.1.4：Windows x64 现已可用。支持 WinFsp，并强制执行 MXC 网络策略。配套的 DSH 0.1.4 和 Pi 0.1.3 新增 Windows 安装与 PowerShell 集成。

- [2026/10/19] 新增 Windows WinFsp 支持，私有会话具备严格持久性，并加入按执行范围审批网络访问（PR #33、PR #35）。
- [2026/10/16] 开源 DeltaBox Lite，并发布介绍文章《DeltaBox Lite: A Lightweight File Sandbox for Terminal AI Agents》。
- [2026/10/14] 发布 v0.1.0 和 v0.1.1，更新 DSH / Pi 集成，修复 macOS 会话中的 read-write 执行问题。
- [2026/09] 扩展 Native Node API 和执行配置档；新增 npm、Homebrew、安装脚本，以及多平台预构建发布流水线。
- [2026/08] 构建 Linux / macOS 文件沙箱、CB-CoW 状态引擎和 diff / commit / abort 工作流；新增 DSH / Pi 集成，支持多个智能体并发私有会话。

查看完整历史

2026

- [10/19] 新增 Windows WinFsp 会话，支持 cbcow-through 和 cbcow-private 两种模式，并修复已有视图目录的访问权限（PR #33）。
- [10/19] 新增按执行范围授权的网络审批：代理限制目标主机和端口，临时授权在命令结束后失效（PR #35）。
- [10/16] 项目开源，并发布介绍文章《DeltaBox Lite: A Lightweight File Sandbox for Terminal AI Agents》。
- [10/15] 新增面向 AI 智能体的安装提示词和环境检查。
- [10/14] 发布 v0.1.0 和 v0.1.1，更新 DSH / Pi 插件和安装指南，并修复 macOS 上受保护的 read-write 执行在会话中的问题（PR #32）。
- [09/22] 新增 npm 启动器、由 tag 触发的多平台预构建、发布工具链、Homebrew 支持和安装脚本（PR #29）。
- [09/19] 新增内嵌原生执行和 Native Node API，并通过原生 API 和命令行对外暴露执行配置档（PR #22、PR #23）。
- [08/31] 新增多智能体并发私有会话，用发布锁仲裁，并优化提交前的暂存和摘要计算（PR #4、PR #14）。
- [08/25] 合并原生 Pi 插件集成，优化 DeltaFS 控制响应传输（PR #8、PR #11）。
- [08/18] 合并 DSH 插件集成，把默认会话状态迁入项目的 .deltabox 目录，并修复状态迁移后 macOS 的会话访问问题。
- [08/15] 新增单命令事务，用 deltabox run --commit / --abort 保留或丢弃改动。
- [08/13] 新增常驻会话命令执行器，复用执行环境，降低多条命令之间的开销。
- [08/10] 新增基于 APFS 和 FSEvents 的原生 macOS CB-CoW 支持，打包原生运行时，并对外暴露结构化会话接口。
- [08/09] 新增私有 CB-CoW 和严格持久化模式，扩展 Linux 文件系统操作支持。
- [08/08] 实现提交偏向的状态引擎，并与 Linux FUSE 集成。
- [08/07] 新增原生 macOS Seatbelt 沙箱后端，开始搭建 CB-CoW 架构。
- [08/06] 新增无需全局服务的持久化会话、持久化审查状态、崩溃恢复，以及更严格的沙箱策略。
- [08/05] 用 Linux Sandlock 会话初始化项目，支持 checkpoint / commit / abort、快速快照、增量状态处理和可读差异。

路线图

- [x] 支持 macOS、Linux、Windows
- [x] 私有工作区
- [x] 快速、可靠的回滚
- [x] Pi 插件
- [x] DSH 插件
- [x] HTTP/HTTPS 代理
- [ ] PTY、stdin 支持
- [ ] 凭据掩码

演示

运行一条命令，查看它产生的变更集，再决定保留还是丢弃：

deltabox-lite transaction demo

亮点

- 原生隔离，不用容器 —— Linux 把 Sandlock/Landlock/ seccomp 与 DeltaFS FUSE 组合起来；macOS 用 Seatbelt 加 APFS 克隆和 FSEvents； Windows 用 MXC 进程安全机制配合 WinFsp 文件系统路由。
- 无需常驻服务的持久会话 —— Linux 自动启动会话级文件系统辅助进程，macOS 自动启动会话级事件辅助进程。持久文件在多个独立的命令行进程之间始终是权威来源；不需要全局守护进程，也不用手动启动服务。
- 三种文件系统模式 —— cbcow-through 让改动立即可见，并把 commit 变成 O(1) 的接受操作。cbcow-private 在私有 reflink/copy 树上运行同一套 DeltaFS 引擎，commit 时只发布被触及的路径。copy-private 保留为兼容回退方案。
- Diff / commit / abort —— 统一文本差异、二进制与大文件标记，以及线性 checkpoint 链。abort 恢复选定的 checkpoint；commit 接受当前状态。
- 审查范围保存点 —— 任务适配器和工具适配器会选出正确的 abort 目标；常规 commit 和 abort 不需要你手动创建 checkpoint。
- 智能体适配器 —— 可选，通过 stdio 走 JSON-RPC，供 Pi 等集成使用；见适配器协议。
- 策略优先 —— 文件系统读写规则、敏感路径拒绝、网络允许/审计、全拒绝与白名单模式、清理过的子进程环境，以及有界的写入与存储。

安装

让 AI 智能体来安装

把下面这段提示词复制到有终端访问权限的 AI 编程智能体里：

Install DeltaBox Lite by following the instructions at
https://raw.githubusercontent.com/delta-box/deltabox-lite/main/install-prompt.txt
Detect my environment, install the appropriate runtime and any DSH or Pi
integration I use, and verify the installation with the disposable smoke test.

纯文本的安装提示词涵盖环境检查、集成配置和验证。你也可以把它的内容直接粘贴给你的智能体。

手动安装

在 macOS 或 Linux 上运行以下命令，安装 deltabox-lite 命令行：

curl -fsSL https://raw.githubusercontent.com/delta-box/deltabox-lite/main/scripts/install.sh | sh

预编译二进制覆盖 macOS（arm64、x64）、Linux（x64、arm64）和 Windows（x64），可在 GitHub release 找到。
在 Windows 上，先安装 WinFsp，然后用 PowerShell：

npm install --global deltabox-lite
deltabox --version

Windows 上的 deltabox 命令直接在 PowerShell 里运行。Pi 的 bash 工具使用 Pi 自己的 shell 选择逻辑，在 Windows 上默认是 Git Bash。命令行本身不依赖 Git Bash。沙箱内执行命令需要 Windows MXC 进程安全支持；如果不可用，会话启动时会报错。

deltabox-lite 命令行也可以通过以下包管理器安装：

Install using npm
npm install --global deltabox-lite

Install using Homebrew
brew install delta-box/tap/deltabox

从源码构建

cargo build --release
export PATH="$PWD/target/release:$PATH"

插件

DSH（DeepSeek Harness）

装好 DeepSeek Harness 后，把插件加到 Web 配置档：

dsh plugin --profile web add dsh-deltabox

Desktop 端打开 Plugins → Add plugin，输入 dsh-deltabox，然后安装。也可以使用 Desktop 自带的命令行：

dsh plugin --profile desktop add dsh-deltabox

配置和审查控制见 DSH 插件指南。

Pi

需要的话先安装 Pi，然后添加扩展：

npm install --global @earendil-works/pi-coding-agent
pi install npm:pi-deltabox

在项目里启动新的 Pi 会话，运行 /sandbox-status 确认扩展已生效。用 /sandbox-review、/sandbox-commit、/sandbox-abort 审查、保留或丢弃改动。配置说明见 Pi 扩展指南，其中包括显式命令隔离设置。

两个集成在 Linux 上都用 FUSE 实现 CB-CoW（需要 /dev/fuse 以及 fusermount3 或 fusermount），macOS 上用 APFS/FSEvents，Windows 上用 WinFsp。

快速开始

第一次做事务，可以建一个只含普通文件的项目，然后丢弃某条命令的改动。不需要包清单，也不需要策略文件：

demo=$(mktemp -d)
cd "$demo"
printf 'original\n' > notes.txt

deltabox run --abort -- sh -c '
printf "sandboxed\n" >> notes.txt
printf "generated\n" > generated.txt
find . -maxdepth 1 -type f -print
'

cat notes.txt
test ! -e generated.txt

命令在沙箱视图里运行，打印 diff，然后中止。原来的 notes.txt 保持不变，generated.txt 被删除。

要保留结果，用同样的单命令接口，换成 --commit：

deltabox run --commit -- sh -c 'printf "accepted by deltabox\n" > accepted.txt'
cat accepted.txt

run 会创建临时事务并在结束后清理。脚本和智能体集成应显式选择 --commit 或 --abort；做出决定后，子进程的退出状态会保留。

要跑多条独立命令，启动持久会话。从项目目录运行的命令可以省略 --project；只有调用 Deltabox 从另一个目录执行：

cd /abs/path/my-project
session_id=$(deltabox session start .)
deltabox exec "$session_id" -- sh -c 'printf "step one\n" > step-one.txt'
deltabox exec "$session_id" -- sh -c 'printf "step two\n" > step-two.txt'
deltabox diff "$session_id"
deltabox commit "$session_id"
deltabox session stop "$session_id"

会话记录默认存放在 <project>/.deltabox，每个项目各自独立。设置 DELTABOX_STATE_DIR=/path/to/state，可以把会话记录和引擎状态改存到任意路径。

Shell 命令语法

deltabox exec 和 deltabox run 直接执行 -- 后面的 argv。不需要 shell 解析的命令，按普通参数传入即可：

deltabox exec "$session_id" -- git status --short
deltabox exec "$session_id" -- curl -fL -o source.tar.gz https://example.com/source.tar.gz

重定向、管道、变量展开、通配符展开、命令列表，都需要显式指定 shell。把完整脚本放进引号里，这样外层宿主 shell 不会在 Deltabox 启动前就执行文件系统操作：

deltabox exec "$session_id" -- sh -c 'printf "%s\n" hello > hello.txt'
deltabox run --abort -- sh -c 'printf "%s\n" trial > trial.txt'
deltabox exec "$session_id" -- sh -c 'find . -type f | sort > files.txt'
deltabox exec "$session_id" -- sh -c 'command-that-may-be-quiet >/dev/null 2>&1'

下面这种写法是错的：宿主 shell 会处理 >，在沙箱事务之外创建 hello.txt：

deltabox exec "$session_id" -- echo hello > hello.txt

只给整条命令加引号、不加 sh -c 也是错的：Deltabox 会把整个字符串当成可执行文件名。沙箱内的命令不会在 stdin 上获得终端，所以 Git 这类工具要用非交互参数。

选择文件系统模式

Linux 和 macOS 默认请求 cbcow-through，原生服务商不可用时会明显回退到 copy-private。Windows 配合 WinFsp 支持 cbcow-through 和 cbcow-private。工作流有要求时，显式指定模式：

deltabox session start /abs/path/my-project --fs-mode copy-private
deltabox session start /abs/path/my-project --fs-mode cbcow-private --require-fs-mode
deltabox session start /abs/path/my-project --fs-mode cbcow-through --require-fs-mode
deltabox session start /abs/path/my-project --fs-mode cbcow-through --durable
deltabox session start /abs/path/my-project --fs-mode cbcow-through --durable --group-commit-ms 2

快速模式是默认模式，能从辅助进程/进程故障中恢复。--durable 增加有序存储屏障；commit 成功即表示改动过的文件、受影响的目录和验收标记都已同步。--group-commit-ms 让并发修改共享同一个 APPLIED 日志屏障，同时保留每次操作各自的成功边界。严格模式要求 cbcow-through 或 cbcow-private；否则启动失败当请求的服务商不可用时，回退到 copy-private。在 macOS 上，快速 cbcow-through 还假定 Deltabox 是项目的唯一写入方。快速 exec 把 FSEvents 记账推迟到下一次状态操作；严格模式在每次结果前关闭哨兵边界，检测外部写入，并拒绝不安全的终止。如果提交前需要主机隔离，请使用 cbcow-private。

工作原理

flowchart LR
A[CLI or agent adapter] --> C[Session coordinator]
C --> X[Lazy session command helper]
X --> Y[Short-lived confined child]
C --> T[Linux cbcow-through]
T --> H[Session-scoped DeltaFS helper]
H --> P[(Host-visible LIVE tree)]
C --> V[Linux cbcow-private]
V --> F[Session-scoped DeltaFS helper]
F --> L[(Private LIVE tree)]
L -->|touched-path commit| P
C --> M[macOS native APFS plus FSEvents]
M --> E[Session-scoped event helper]
E --> P
E --> L
C --> R[copy-private fallback]
R --> S[(Private working tree)]
S -->|commit| P

在 Linux 上，如果 FUSE 可用，session start 会启动一个辅助进程，通过偏向提交的状态引擎挂载主机项目。写入会先记录回滚数据，再通过 DeltaFS 更新主机树；提交接受当前状态，终止则重放撤销记录。cbcow-private 保留同样的快速逐命令路径，同时把它的 LIVE 树对主机隐藏，直到经过冲突检查的提交。在 copy-private 中，每条命令更新一个持久化的私有工作树，提交再把它发布到项目。
在 macOS 上，同样的模式使用 APFS 克隆状态和一个可重启的 FSEvents 辅助进程，而不是挂载。辅助进程只负责保持事件流活跃；持久化的游标和索引仍是权威来源。
第一次 CB-CoW exec 还会启动一个可重启的命令辅助进程。后续命令行操作复用它已预热的 Sandlock worker（Linux）或 Seatbelt 配置档/代理（macOS），但不会让该辅助进程成为权威的会话状态。会话真相的来源是持久化文件，而不是长期运行的进程。参见会话语义。

策略

session start --policy policy.toml 接受文件系统、网络和资源限制。默认智能体策略使用 allow_audit 网络模式，拒绝常见敏感路径，只向命令传递一小份环境变量允许列表，单次直接写入上限为 16 MiB，待处理的已添加/已修改文件内容上限为 1 GiB。网络策略也可以改为拒绝所有访问，或只允许显式的主机和端口目标：

[network]
mode = "allowlist"
allow = ["registry.npmjs.org:443", "127.0.0.1:3000"]

[limits]
max_write_bytes = 16777216
max_storage_bytes = 1073741824

完整模式和强制执行语义参见策略参考，路径映射和工具支持参见 macOS 兼容性。

策略是会话的常设广度。单条命令可以请求一个更宽的执行配置档——workspace-write（默认）或 read-write——这样 session.exec 调用就能访问宿主机文件系统，而无需切换会话：

deltabox exec "$SESSION" --project /abs/path/my-project \
--execution-profile read-write -- sh -c 'sudo apt-get install -y ripgrep'

无论用哪种配置档，工作区改动对 diff、commit 和 abort 都保持可见。Linux FUSE 和私有工作区模式拒绝直接访问底层项目；macOS cbcow-through 写入真实项目，并用 APFS/FSEvents 跟踪这些改动。两种情况下，引擎状态和辅助端点都保持拒绝访问。工作区之外的宿主机写入无法回滚。

性能

在 x86-server 上测得（Linux 6.18，ext4，release 构建）。每行报告五次预热后的 50 条空操作命令。Deltabox 在一个 cbcow-through 会话上使用相互独立的命令行进程。

| Runner | 10 files p50 / p95 | 200 files p50 / p95 | 1000 files p50 / p95 |
| cbcow-through | 13.7 / 15.5 ms | 14.3 / 15.4 ms | 13.2 / 14.7 ms |
| raw Sandlock | 8.1 / 9.4 ms | 8.2 / 9.0 ms | 8.1 / 8.9 ms |
| plain shell | 1.3 / 1.7 ms | 1.2 / 1.6 ms | 1.2 / 1.5 ms |

空操作路径不会按命令扫描或复制项目。在扩展性基准测试中，空的 DeltaFS checkpoint 和 commit 操作始终低于 1 ms。

当工作负载产生大量小改动时，增量驱动路径可以胜过反复执行 Sandlock copy-up 的工作。

| Microbenchmark | cbcow-through p50 / p95 | raw Sandlock p50 / p95 | Faster path |
| One 4 KiB write in a 256 MiB existing file | 46.4 / 47.3 ms | 166.0 / 187.7 ms | cbcow-through |
| 16 commands, one 4 KiB write per 32 MiB file, one final commit | 509.0 / 509.6 ms | 4809.5 / 5761.2 ms | cbcow-through |

raw Sandlock 没有跨命令的持久会话，所以第二行会独立提交每条一次性命令。

在 macOS 上，原生服务商在会话开始时一次性物化其 APFS 已接受基线。快速命令不会按调用克隆或扫描项目；status、diff、checkpoint、commit 和 abort 会关闭 FSEvents 对账边界。私有模式还会额外物化一棵私有 APFS LIVE 树，因此用更多启动和命令路径开销换取提交前的宿主机隔离。

项目结构

- crates/deltabox-core —— 会话、checkpoint、diff/commit/abort、策略、日志、平台后端。
- crates/deltabox-cli —— deltabox 命令行二进制。
- crates/deltabox-node - deltabox 的 Node-API 绑定。
- deltafs-fuse —— 独立的提交偏向状态引擎、FUSE 适配器、辅助程序和本地控制协议。
- plugin - dsh 和 pi 插件
- npm - npm 包
- docs/policy.md —— 策略 schema 和执行边界。
- docs/macos.md —— macOS 后端行为与兼容性矩阵。

引用

如果你觉得 deltabox-lite 有用，请引用 DeltaBox 的原始论文（基于 microVM）或本 github 仓库：

@misc{dong2026deltaboxscalingstatefulai,
title={DeltaBox: Scaling Stateful AI Agents with Millisecond-Level Sandbox Checkpoint/Rollback},
author={Yunpeng Dong and Jingkai He and Shiqi Liu and Yuze Hou and Dong Du and Zhonghu Xu and Si Yu and Baochuan Yang and Yubin Xia and Haibo Chen},
year={2026},
eprint={2605.22781},
archivePrefix={arXiv},
primaryClass={cs.OS},
url={https://arxiv.org/abs/2605.22781},
}

许可证

Apache-2.0。

致谢

本项目用到了现有沙箱项目的优秀成果，例如 sandlock。

⭐ 如果你觉得 deltabox-lite 有用，就给这个仓库点个 Star 吧！