branch-sandbox — Isolated Branch Execution

Sandboxed branches of mutable state. Run code in isolation, compare outputs, merge results — all without affecting the main environment.

What This Gives You

• Sandboxed branches — create isolated copies of state for safe experimentation
• Branch execution — run code inside a branch without affecting the main state
• Diff comparison — compare branch outputs against the main environment
• Smart merging — merge branch results back with conflict detection and resolution
• Status tracking — CREATED → ACTIVE → COMPLETED → MERGED / ABORTED lifecycle

Quick Start

pip install branch-sandbox

from branch_sandbox import Sandbox, SandboxConfig, Branch, MergeEngine

# Create a sandbox
sandbox = Sandbox(config=SandboxConfig(base_state={"counter": 0, "data": []}))

# Create a branch for experimentation
branch = sandbox.create_branch("experiment-1")

# Execute in isolation
result = sandbox.execute(branch, lambda state: {**state, "counter": state["counter"] + 1})
print(branch.status)  # ACTIVE

# Compare with main
comparison = sandbox.compare(branch)
print(comparison.diff)  # {"counter": {"main": 0, "branch": 1}}

# Merge back
merge = MergeEngine()
result = merge.merge(sandbox.main, branch)
print(result.status)  # MERGED

API Reference

Sandbox(config) — create_branch(name), execute(branch, fn), compare(branch)

SandboxConfig(base_state, max_branches=None)

Branch(name, status=CREATED) · BranchStatus — CREATED, ACTIVE, COMPLETED, MERGED, ABORTED

SandboxExecutor — Execute functions inside branch context

BranchComparison / DiffRecord — Side-by-side state comparison

MergeEngine — merge(main, branch) → MergeResult with conflict detection

How It Fits

The isolation layer for the SuperInstance fleet. Agents experiment in sandboxes before committing changes to production.

• claude-code-vessel — Containerized execution (uses sandboxes)
• cicd-agent — CI/CD (tests in sandboxes)
• guard-constraints — Safety constraints

Testing

pytest tests/

Installation

pip install branch-sandbox

Python 3.10+. MIT license.