delta-box/deltabox-lite

deltabox-lite is a standalone sandbox runtime for AI coding agents. Agents keep full execution freedom inside a confined filesystem view, and every change they make can be reviewed, committed, or aborted - per task or per tool call. Linux defaults to a commit-biased FUSE view; macOS uses native APFS clones and FSEvents. Private modes keep changes hidden from the host until commit.

Think of it as Git for agent sessions: less ceremony, more control, and no anxiety about binary or large files.

Run a command, inspect its change set, and choose whether to keep or discard it:

• Native isolation, not a container - Linux composes Sandlock/Landlock/ seccomp with DeltaFS FUSE; macOS uses Seatbelt plus APFS clones and FSEvents.
• Service-free durable sessions - Linux starts a session-scoped filesystem helper and macOS starts a session-scoped event helper automatically. Durable files remain authoritative across independent CLI processes; no global daemon or manual service startup is required.
• Three filesystem modes - cbcow-through makes changes visible immediately and makes commit an O(1) acceptance operation. cbcow-private runs the same DeltaFS engine over a private reflink/copy tree and publishes only touched paths at commit. copy-private remains the compatibility fallback.
• Diff / commit / abort - unified text diffs, binary and large-file markers, and a linear checkpoint chain. Abort restores the selected checkpoint; commit accepts the current state.
• Review-scope savepoints — task and tool adapters choose the correct abort target; normal commit and abort do not require a user-created checkpoint.
• Agent adapters — optional JSON-RPC over stdio for Pi and other integrations; see the adapter protocol.
• Policy-first — filesystem read/write rules, secret-path denial, network allow/audit, deny-all and allowlist modes, scrubbed child environments, and bounded writes/storage.

Copy this prompt into an AI coding agent with terminal access:

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.

The plain-text installation prompt covers environment checks, integration setup, and verification. You can also paste its contents directly into your agent.

Run the following on Mac or Linux to install deltabox-lite CLI:

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

The prebuilt binaries ship for macOS (arm64, x64) and Linux (x64, arm64) can be found on GitHub release.

deltabox-lite CLI can also be installed via the following package managers:

# 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"

With DeepSeek Harness installed, add the plugin to your Web profile:

dsh plugin --profile web add dsh-deltabox

For Desktop, open Plugins → Add plugin, enter dsh-deltabox, and install it. Alternatively, use Desktop's bundled CLI:

dsh plugin --profile desktop add dsh-deltabox

DSH plugin guide for configuration and review controls.

Install Pi if needed, then add the extension:

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

Start a new Pi session in your project and run /sandbox-status to verify that the extension is active. Use /sandbox-review, /sandbox-commit, and /sandbox-abort to review, keep, or discard changes. See the Pi extension guide for configuration, including explicit command isolation settings.

Both integrations use FUSE on Linux for CB-CoW (/dev/fuse and fusermount3 or fusermount) and APFS/FSEvents on macOS.

For a first transaction, create a project with one ordinary file and discard a command's changes. No package manifest or policy file is needed:

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

The command runs inside the sandbox view, prints the diff, and then aborts. The original notes.txt remains unchanged and generated.txt is removed.

To keep a result, use the same one-command interface with --commit:

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

run creates and cleans up a temporary transaction. Scripts and agent integrations should select --commit or --abort explicitly; the child exit status is preserved after that decision.

For multiple independent commands, start a persistent session. Commands run from the project directory can omit --project; use it only when invoking Deltabox from another directory:

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"

Session records live in <project>/.deltabox by default, so each project stays self-contained. Set DELTABOX_STATE_DIR=/path/to/state to relocate session records and engine state to an arbitrary path instead.

deltabox exec and deltabox run execute the argv after -- directly. Commands that do not require shell parsing can be passed as ordinary arguments:

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

Redirection, 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:

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'

This form is wrong because the host shell handles > and creates hello.txt outside the sandbox transaction:

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

Quoting the whole command without sh -c is also wrong: Deltabox would treat the complete string as an executable filename. Sandboxed commands do not receive a terminal on stdin, so use non-interactive flags for tools such as Git.

Linux and macOS request cbcow-through by default and visibly fall back to copy-private if the native provider is unavailable. Select the mode explicitly when a workflow requires it:

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

Fast mode is the default and recovers helper/process failures. --durable adds ordered storage barriers; success from commit means changed files, affected directories, and the acceptance marker are synchronized. --group-commit-ms lets concurrent mutations share an APPLIED journal barrier while preserving that per-operation success boundary. Strict mode requires cbcow-through or cbcow-private; startup fails instead of falling back to copy-private when the requested provider is unavailable. On macOS, fast cbcow-through also assumes Deltabox is the exclusive project writer. Fast exec defers FSEvents accounting to the next state operation; strict mode closes a sentinel boundary before each result, detects external writes, and refuses an unsafe abort. Use cbcow-private when host isolation is required before commit.

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

On Linux with FUSE available, session start launches a helper that mounts the host project through the commit-biased state engine. Writes update the host tree through DeltaFS after recording rollback data; commit accepts the current state and abort replays undo records. cbcow-private preserves the same fast per-command path while keeping its LIVE tree hidden from the host until a conflict-checked commit. In copy-private, each command updates a durable private working tree and commit publishes it to the project. On macOS, the same modes use APFS-cloned state and a restartable FSEvents helper instead of a mount. The helper only keeps the event stream warm; persisted cursors and indexes remain authoritative. The first CB-CoW exec also launches a restartable command helper. Later CLI operations reuse its warm Sandlock worker on Linux or Seatbelt profile/proxy on macOS without making that helper authoritative session state. Durable files, not a long-running process, remain the source of session truth. See session semantics.

session start --policy policy.toml accepts filesystem, network, and resource limits. The default agent policy uses the allow_audit network mode, denies common secret paths, passes only a small environment allowlist to commands, caps one direct write at 16 MiB, and caps pending added/modified file content at 1 GiB. Network policy can instead deny all access or allow only explicit host-and-port targets:

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

[limits]
max_write_bytes = 16777216
max_storage_bytes = 1073741824

See policy reference for the full schema and enforcement semantics, and macOS compatibility for path mapping and tool support.

The policy is the session's standing breadth. A single command can request a wider execution profile — workspace-write (default) or read-write — so a session.exec call can reach the host filesystem without changing the session:

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

Workspace changes stay visible to diff, commit, and abort under either profile. Linux FUSE and private-workspace modes deny direct access to the backing project; macOS cbcow-through writes the real project and tracks those changes with APFS/FSEvents. Engine state and helper endpoints stay denied in both cases. Host writes outside the workspace cannot be rolled back.

Measured on x86-server (Linux 6.18, ext4, release build). Each row reports 50 no-op commands after five warmups. Deltabox uses independent CLI processes over one cbcow-through session.

The 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.

The delta-driven path can outperform repeated Sandlock copy-up work when a workload makes many small changes.

Raw Sandlock has no durable cross-command session, so the second row commits each one-shot command independently.

On macOS, the native provider materializes its APFS accepted base once at session start. Fast commands do not clone or scan the project per invocation; status, diff, checkpoint, commit, and abort close the FSEvents reconciliation boundary. Private mode additionally materializes a private APFS LIVE tree and therefore trades more startup and command-path work for pre-commit host isolation.

• crates/deltabox-core — sessions, checkpoints, diff/commit/abort, policy, journal, platform backends.
• crates/deltabox-cli — the deltabox command-line binary.
• crates/deltabox-node - the deltabox Node-API bindings.
• deltafs-fuse — the standalone commit-biased state engine, FUSE adapter, helper, and local control protocol.
• plugin - dsh and pi plugin
• npm - npm package
• docs/policy.md — policy schema and enforcement boundaries.
• docs/macos.md — macOS backend behavior and compatibility matrix.

If you find deltabox-lite useful, please cite the original paper of DeltaBox (which is based on microVM) or this github repo:

@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.

This project utilizes excellent work of existing sandbox projects like sandlock.

⭐ Star this repo if you find deltabox-lite helpful!