{"slug": "deltabox-a-rollback-able-agent-sandbox", "title": "Deltabox: A rollback-able agent sandbox", "summary": "DeltaBox Lite launched as a standalone sandbox runtime that gives AI coding agents a confined filesystem view with explicit diff, commit, and abort semantics per task or per tool call. The tool composes Sandlock, Landlock, and seccomp with DeltaFS FUSE on Linux and uses Seatbelt plus APFS clones and FSEvents on macOS, offering three filesystem modes — cbcow-through, cbcow-private, and copy-private — with prebuilt binaries for macOS (arm64, x64) and Linux (x64, arm64) available via curl install script, npm, Homebrew, and Cargo. It ships optional JSON-RPC over stdio adapters for Pi and DeepSeek Harness, plus policy controls covering filesystem read/write rules, secret-path denial, and network allow/audit modes.", "body_md": "**Lightweight, agent-native sandboxing with diff · commit · abort.**\n\nGive agents a confined workspace with explicit diff, commit, and abort semantics.\n\ndeltabox-lite is a standalone sandbox runtime for AI coding agents. Agents keep\nfull execution freedom inside a confined filesystem view, and every change\nthey make can be **reviewed**, **committed**, or **aborted** - per task or per\ntool call. Linux defaults to a commit-biased FUSE view; macOS uses native APFS\nclones and FSEvents. Private modes keep changes hidden from the host until\ncommit.\n\nThink of it as Git for agent sessions: less ceremony, more control, and no anxiety about binary or large files.\n\nRun a command, inspect its change set, and choose whether to keep or discard it:\n\n- **Native isolation, not a container** - Linux composes Sandlock/Landlock/\nseccomp with DeltaFS FUSE; macOS uses Seatbelt plus APFS clones and FSEvents.\n- **Service-free durable sessions** - Linux starts a session-scoped filesystem\nhelper and macOS starts a session-scoped event helper automatically. Durable\nfiles remain authoritative across independent CLI processes; no global daemon\nor manual service startup is required.\n- **Three filesystem modes** -`cbcow-through` makes changes visible\nimmediately and makes commit an O(1) acceptance operation.`cbcow-private` runs the same DeltaFS engine over a private reflink/copy tree and publishes\nonly touched paths at commit.`copy-private` remains the compatibility\nfallback.\n- **Diff / commit / abort** - unified text diffs, binary and large-file\nmarkers, and a linear checkpoint chain. Abort restores the selected\ncheckpoint; commit accepts the current state.\n- **Review-scope savepoints** — task and tool adapters choose the correct abort\ntarget; normal commit and abort do not require a user-created checkpoint.\n- **Agent adapters** — optional JSON-RPC over stdio for Pi and other\nintegrations; see the[adapter protocol](https://github.com/delta-box/deltabox-lite/blob/main/docs/protocol.md) .\n- **Policy-first** — filesystem read/write rules, secret-path denial, network\nallow/audit, deny-all and allowlist modes, scrubbed child environments, and\nbounded writes/storage.\n\nCopy this prompt into an AI coding agent with terminal access:\n\n```\nInstall DeltaBox Lite by following the instructions at\nhttps://raw.githubusercontent.com/delta-box/deltabox-lite/main/install-prompt.txt\nDetect my environment, install the appropriate runtime and any DSH or Pi\nintegration I use, and verify the installation with the disposable smoke test.\n```\n\nThe plain-text [installation prompt](https://github.com/delta-box/deltabox-lite/blob/main/install-prompt.txt) covers environment\nchecks, integration setup, and verification. You can also paste its contents\ndirectly into your agent.\n\nRun the following on Mac or Linux to install deltabox-lite CLI:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/delta-box/deltabox-lite/main/scripts/install.sh | sh\n```\n\nThe prebuilt binaries ship for macOS (arm64, x64) and Linux (x64, arm64) can be found on\n[GitHub release](https://github.com/delta-box/deltabox-lite/releases).\n\ndeltabox-lite CLI can also be installed via the following package managers:\n\n```\n# Install using npm\nnpm install --global deltabox-lite\n# Install using Homebrew\nbrew install delta-box/tap/deltabox\ncargo build --release\nexport PATH=\"$PWD/target/release:$PATH\"\n```\n\nWith DeepSeek Harness installed, add the plugin to your Web profile:\n\n```\ndsh plugin --profile web add dsh-deltabox\n```\n\nFor Desktop, open **Plugins → Add plugin**, enter `dsh-deltabox`, and install\nit. Alternatively, use Desktop's bundled CLI:\n\n```\ndsh plugin --profile desktop add dsh-deltabox\n```\n\n[DSH plugin guide](https://github.com/delta-box/dsh-deltabox#readme) for\nconfiguration and review controls.\n\nInstall Pi if needed, then add the extension:\n\n```\nnpm install --global @earendil-works/pi-coding-agent\npi install npm:pi-deltabox\n```\n\nStart a new Pi session in\nyour project and run `/sandbox-status` to verify that the extension is active.\nUse `/sandbox-review`, `/sandbox-commit`, and `/sandbox-abort` to review, keep,\nor discard changes. See the\n[Pi extension guide](https://github.com/delta-box/pi-deltabox#readme) for\nconfiguration, including explicit command isolation settings.\n\nBoth integrations use FUSE on Linux for CB-CoW (`/dev/fuse` and `fusermount3`\nor `fusermount`) and APFS/FSEvents on macOS.\n\nFor a first transaction, create a project with one ordinary file and discard a command's changes. No package manifest or policy file is needed:\n\n```\ndemo=$(mktemp -d)\ncd \"$demo\"\nprintf 'original\\n' > notes.txt\n\ndeltabox run --abort -- sh -c '\n  printf \"sandboxed\\n\" >> notes.txt\n  printf \"generated\\n\" > generated.txt\n  find . -maxdepth 1 -type f -print\n'\n\ncat notes.txt\ntest ! -e generated.txt\n```\n\nThe command runs inside the sandbox view, prints the diff, and then aborts. The\noriginal `notes.txt` remains unchanged and `generated.txt` is removed.\n\nTo keep a result, use the same one-command interface with `--commit`:\n\n```\ndeltabox run --commit -- sh -c 'printf \"accepted by deltabox\\n\" > accepted.txt'\ncat accepted.txt\n```\n\n`run` creates and cleans up a temporary transaction. Scripts and agent\nintegrations should select `--commit` or `--abort` explicitly; the child exit\nstatus is preserved after that decision.\n\nFor multiple independent commands, start a persistent session. Commands run from\nthe project directory can omit `--project`; use it only when invoking Deltabox\nfrom another directory:\n\n```\ncd /abs/path/my-project\nsession_id=$(deltabox session start .)\ndeltabox exec \"$session_id\" -- sh -c 'printf \"step one\\n\" > step-one.txt'\ndeltabox exec \"$session_id\" -- sh -c 'printf \"step two\\n\" > step-two.txt'\ndeltabox diff \"$session_id\"\ndeltabox commit \"$session_id\"\ndeltabox session stop \"$session_id\"\n```\n\nSession records live in `<project>/.deltabox` by default, so each project stays\nself-contained. Set `DELTABOX_STATE_DIR=/path/to/state` to relocate session\nrecords and engine state to an arbitrary path instead.\n\n`deltabox exec` and `deltabox run` execute the argv after `--` directly. Commands\nthat do not require shell parsing can be passed as ordinary arguments:\n\n```\ndeltabox exec \"$session_id\" -- git status --short\ndeltabox exec \"$session_id\" -- curl -fL -o source.tar.gz https://example.com/source.tar.gz\n```\n\nRedirection, pipes, variable expansion, globbing, and command lists require an explicit shell. Keep the complete script inside quotes so the outer host shell cannot perform the filesystem operation before Deltabox starts:\n\n```\ndeltabox exec \"$session_id\" -- sh -c 'printf \"%s\\n\" hello > hello.txt'\ndeltabox run --abort -- sh -c 'printf \"%s\\n\" trial > trial.txt'\ndeltabox exec \"$session_id\" -- sh -c 'find . -type f | sort > files.txt'\ndeltabox exec \"$session_id\" -- sh -c 'command-that-may-be-quiet >/dev/null 2>&1'\n```\n\nThis form is wrong because the host shell handles `>` and creates `hello.txt`\noutside the sandbox transaction:\n\n```\ndeltabox exec \"$session_id\" -- echo hello > hello.txt\n```\n\nQuoting the whole command without `sh -c` is also wrong: Deltabox would treat\nthe complete string as an executable filename. Sandboxed commands do not receive\na terminal on stdin, so use non-interactive flags for tools such as Git.\n\nLinux and macOS request `cbcow-through` by default and visibly fall back to\n`copy-private` if the native provider is unavailable. Select the mode\nexplicitly when a workflow requires it:\n\n```\ndeltabox session start /abs/path/my-project --fs-mode copy-private\ndeltabox session start /abs/path/my-project --fs-mode cbcow-private --require-fs-mode\ndeltabox session start /abs/path/my-project --fs-mode cbcow-through --require-fs-mode\ndeltabox session start /abs/path/my-project --fs-mode cbcow-through --durable\ndeltabox session start /abs/path/my-project --fs-mode cbcow-through --durable --group-commit-ms 2\n```\n\nFast mode is the default and recovers helper/process failures. `--durable`\nadds ordered storage barriers; success from commit means changed files,\naffected directories, and the acceptance marker are synchronized.\n`--group-commit-ms` lets concurrent mutations share an `APPLIED` journal\nbarrier while preserving that per-operation success boundary.\nStrict mode requires `cbcow-through` or `cbcow-private`; startup fails instead\nof falling back to `copy-private` when the requested provider is unavailable.\nOn macOS, fast `cbcow-through` also assumes Deltabox is the exclusive project\nwriter. Fast `exec` defers FSEvents accounting to the next state operation;\nstrict mode closes a sentinel boundary before each result, detects external\nwrites, and refuses an unsafe abort. Use `cbcow-private` when host isolation is\nrequired before commit.\n\n``` php\nflowchart LR\n    A[CLI or agent adapter] --> C[Session coordinator]\n    C --> X[Lazy session command helper]\n    X --> Y[Short-lived confined child]\n    C --> T[Linux cbcow-through]\n    T --> H[Session-scoped DeltaFS helper]\n    H --> P[(Host-visible LIVE tree)]\n    C --> V[Linux cbcow-private]\n    V --> F[Session-scoped DeltaFS helper]\n    F --> L[(Private LIVE tree)]\n    L -->|touched-path commit| P\n    C --> M[macOS native APFS plus FSEvents]\n    M --> E[Session-scoped event helper]\n    E --> P\n    E --> L\n    C --> R[copy-private fallback]\n    R --> S[(Private working tree)]\n    S -->|commit| P\n```\n\nOn Linux with FUSE available, `session start` launches a helper that mounts the\nhost project through the commit-biased state engine. Writes update the host\ntree through DeltaFS after recording rollback data; commit accepts the current\nstate and abort replays undo records. `cbcow-private` preserves the same fast\nper-command path while keeping its `LIVE` tree hidden from the host until a\nconflict-checked commit. In `copy-private`, each command updates a durable\nprivate working tree and commit publishes it to the project.\nOn macOS, the same modes use APFS-cloned state and a restartable FSEvents helper\ninstead of a mount. The helper only keeps the event stream warm; persisted\ncursors and indexes remain authoritative.\nThe first CB-CoW `exec` also launches a restartable command helper. Later CLI\noperations reuse its warm Sandlock worker on Linux or Seatbelt profile/proxy on\nmacOS without making that helper authoritative session state. Durable files,\nnot a long-running process, remain the source of session truth. See [session\nsemantics](https://github.com/delta-box/deltabox-lite/blob/main/docs/session-semantics.md).\n\n`session start --policy policy.toml` accepts filesystem, network, and resource\nlimits. The default agent policy uses the `allow_audit` network mode, denies\ncommon secret paths, passes only a small environment allowlist to commands,\ncaps one direct write at 16 MiB, and caps pending added/modified file content at\n1 GiB. Network policy can instead deny all access or allow only explicit\nhost-and-port targets:\n\n```\n[network]\nmode = \"allowlist\"\nallow = [\"registry.npmjs.org:443\", \"127.0.0.1:3000\"]\n\n[limits]\nmax_write_bytes = 16777216\nmax_storage_bytes = 1073741824\n```\n\nSee [policy reference](https://github.com/delta-box/deltabox-lite/blob/main/docs/policy.md) for the full schema and enforcement\nsemantics, and [macOS compatibility](https://github.com/delta-box/deltabox-lite/blob/main/docs/macos.md) for path mapping and tool\nsupport.\n\nThe policy is the session's standing breadth. A single command can request a\nwider *execution profile* — `workspace-write` (default) or `read-write` — so a\n`session.exec` call can reach the host filesystem without changing the session:\n\n```\ndeltabox exec \"$SESSION\" --project /abs/path/my-project \\\n  --execution-profile read-write -- sh -c 'sudo apt-get install -y ripgrep'\n```\n\nWorkspace changes stay visible to diff, commit, and abort under either profile.\nLinux FUSE and private-workspace modes deny direct access to the backing project;\nmacOS `cbcow-through` writes the real project and tracks those changes with\nAPFS/FSEvents. Engine state and helper endpoints stay denied in both cases.\nHost writes outside the workspace cannot be rolled back.\n\nMeasured on x86-server (Linux 6.18, ext4, release build). Each row reports 50\nno-op commands after five warmups. Deltabox uses independent CLI processes over\none `cbcow-through` session.\n\n| Runner | 10 files p50 / p95 | 200 files p50 / p95 | 1000 files p50 / p95 | \n|---|---|---|---|\n| `cbcow-through` | 13.7 / 15.5 ms | 14.3 / 15.4 ms | 13.2 / 14.7 ms | \n| raw Sandlock | 8.1 / 9.4 ms | 8.2 / 9.0 ms | 8.1 / 8.9 ms | \n| plain shell | 1.3 / 1.7 ms | 1.2 / 1.6 ms | 1.2 / 1.5 ms | \n\nThe no-op path does not scan or copy the project per command. Empty DeltaFS checkpoint and commit operations remain below 1 ms in the scaling benchmark.\n\nThe delta-driven path can outperform repeated Sandlock copy-up work when a workload makes many small changes.\n\n| Microbenchmark | `cbcow-through` p50 / p95 | raw Sandlock p50 / p95 | Faster path | \n|---|---|---|---|\n| One 4 KiB write in a 256 MiB existing file | 46.4 / 47.3 ms | 166.0 / 187.7 ms | `cbcow-through` | \n| 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` | \n\nRaw Sandlock has no durable cross-command session, so the second row commits each one-shot command independently.\n\nOn macOS, the native provider materializes its APFS accepted base once at\nsession start. Fast commands do not clone or scan the project per invocation;\nstatus, diff, checkpoint, commit, and abort close the FSEvents reconciliation\nboundary. Private mode additionally materializes a private APFS `LIVE` tree and\ntherefore trades more startup and command-path work for pre-commit host\nisolation.\n\n- `crates/deltabox-core` — sessions, checkpoints, diff/commit/abort, policy,\njournal, platform backends.\n- `crates/deltabox-cli` — the`deltabox` command-line binary.\n- `crates/deltabox-node` - the`deltabox` Node-API bindings.\n- `deltafs-fuse` — the standalone commit-biased state engine, FUSE adapter,\nhelper, and local control protocol.\n- `plugin` - dsh and pi plugin\n- `npm` - npm package\n- `docs/policy.md` — policy schema and enforcement boundaries.\n- `docs/macos.md` — macOS backend behavior and compatibility matrix.\n\nIf you find deltabox-lite useful, please cite the original paper of DeltaBox (which is based on microVM) or this github repo:\n\n```\n@misc{dong2026deltaboxscalingstatefulai,\n      title={DeltaBox: Scaling Stateful AI Agents with Millisecond-Level Sandbox Checkpoint/Rollback}, \n      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},\n      year={2026},\n      eprint={2605.22781},\n      archivePrefix={arXiv},\n      primaryClass={cs.OS},\n      url={https://arxiv.org/abs/2605.22781}, \n}\n```\n\nApache-2.0.\n\nThis project utilizes excellent work of existing sandbox projects like **[`sandlock`](https://github.com/multikernel/sandlock)**.\n\n**⭐ Star this repo if you find deltabox-lite helpful!**", "url": "https://wpnews.pro/news/deltabox-a-rollback-able-agent-sandbox", "canonical_source": "https://github.com/delta-box/deltabox-lite", "published_at": "2026-10-15 14:44:12+00:00", "updated_at": "2026-10-15 14:55:08.574407+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["DeltaBox Lite", "Sandlock", "Landlock", "seccomp", "DeltaFS", "Seatbelt", "APFS", "DeepSeek Harness"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/deltabox-a-rollback-able-agent-sandbox", "markdown": "https://wpnews.pro/news/deltabox-a-rollback-able-agent-sandbox.md", "text": "https://wpnews.pro/news/deltabox-a-rollback-able-agent-sandbox.txt", "jsonld": "https://wpnews.pro/news/deltabox-a-rollback-able-agent-sandbox.jsonld"}}