statebox

README

Statebox

Branchable state sandboxes for AI coding agents.

Run AI coding agents inside an isolated sandbox: a git worktree paired with a copy-on-fork SQLite branch. Inspect what changed, promote what works, discard the rest. No daemon. No proxy. Just files and git.

Killer demo

statebox init --non-interactive --adapter raw-sqlite --db-path ./dev.db

# Manual sandbox: you (or Claude Code) drive it directly.
statebox sandbox create --name foo
# ...edit files in ../.statebox-worktrees/<repo>/foo, write migrations,
#  run them against $SANDBOX_DB_PATH ...
statebox diff foo            # live diff, read-only, no side effects
statebox promote foo --yes   # auto-finalizes + merges + applies migrations

# Or wrapped agent: spawn a sub-process inside a fresh sandbox.
statebox agent run -- bash scripts/agent_stub.sh
statebox diff <run-id>
statebox promote <run-id> --yes

The whole product premise is that your code never has to know about the sandbox — the env var your app reads just points somewhere different inside a run. If a demo bypasses that with a hard-coded ./dev.db, it's teaching the wrong habit.

Install

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/Seiraiyu/statebox/main/install.sh | sh

Drops a static statebox binary into ~/.local/bin (or /usr/local/bin if you swap sh for sudo sh). Linux and macOS, amd64 and arm64. No Go toolchain required.

Knobs:

• STATEBOX_VERSION=v0.2.0 curl ... | sh to pin a version.
• STATEBOX_INSTALL_DIR=/opt/bin curl ... | sh to install elsewhere.

From source (Go required)

go install github.com/seiraiyu/statebox/cmd/statebox@latest

Build locally

git clone https://github.com/Seiraiyu/statebox && cd statebox && make install

How it works

Every agent run creates a sandbox:

• A git worktree at ../.statebox-worktrees/<repo>/<run-id>/ on a fresh statebox/<run-id> branch.
• A sandbox SQLite database copied from a baseline (VACUUM INTO, sha256-deduped).
• Env-var redirection: the configured database.sandbox_path_env (e.g. DATABASE_URL) is rewritten in the agent's env to point at the sandbox DB. No proxy, no driver patching.

When the agent finishes:

• The worktree's diff goes into runs/<id>/files.diff.
• The schema diff between baseline and sandbox lands in schema.diff.
• A row-count delta (with optional sample rows) goes into db.diff.json.
• summary.json aggregates counts.
• metadata.json records the run state, baseline commit, and a redacted env view.

statebox promote <id> merges the branch into main with --no-ff and runs the configured migrations command against the main DB. Failure mid-promote is reported with a git revert <merge-sha> hint.

statebox discard <id> removes the worktree, branch, and sandbox DB. With --purge it also deletes the run artifact dir, leaving only a tombstone in the ledger.

Commands

Command	Purpose
statebox init	Scaffold statebox.yml + .gitignore + .statebox/
statebox snapshot create [--name X]	Take a baseline of the dev DB
statebox snapshot list	List baselines
statebox sandbox create	Create a sandbox without running an agent
statebox sandbox run -- <cmd>	Run an agent in a fresh sandbox (alias: statebox agent run)
statebox sandbox finalize <id>	Explicit freeze: write artifacts, transition to completed
statebox sandbox diff <id> (or statebox diff <id>)	Read-only diff: live for active, frozen for terminal
statebox sandbox promote <id> (or statebox promote <id>)	Auto-finalize + merge + apply migrations
statebox sandbox discard <id> [--purge] (or statebox discard <id>)	Remove sandbox; idempotent across all states
statebox sandbox list (or statebox list)	List sandboxes
statebox sandbox show <id> (or statebox show <id>)	Show sandbox metadata + artifact paths
statebox status [--json]	Operator dashboard
statebox prune --older-than 7d	Discard old sandboxes
statebox reset [--all]	Wipe sandboxes (and baselines with --all)

Adapters

Adapter	Default migrations.apply
raw-sqlite	sqlite3 < migrations/*.sql (lex order)
prisma	npx prisma migrate deploy
drizzle	npx drizzle-kit push
knex	npx knex migrate:latest

Status

Pre-release. See the design and the implementation plan. Step-by-step setup in docs/getting-started.md.