smart_box

smart_box is a local reversible sandbox system for Coding Agent task execution.

Its core goal: allow Coding Agents (SmartExpert, SmartCoder, etc.) to perform file modifications, command execution, dependency installation, experimental fixes, code generation, diff viewing, checkpoint rollback, and patch export — without directly polluting the real project directory.

When a Coding Agent runs autonomously, it may:

• Modify source files incorrectly
• Install conflicting dependencies
• Remove critical files
• Produce untested patches

smart_box provides a safety net: every operation happens inside an isolated box first. The user can inspect, verify, and then explicitly apply changes to the real project.

gem install smart_box

Or via Bundler:

gem "smart_box"

# Create a box from current project (copy mode)
smart_box create --source . --id task-001 --mode copy

# Run a command inside the box
smart_box run --id task-001 -- bundle install

# Create a checkpoint
smart_box checkpoint --id task-001 --name "after bundle install"

# View changes
smart_box diff --id task-001

# Export patch
smart_box export-patch --id task-001 --output fix.patch

# Rollback to initial state
smart_box rollback --id task-001 --checkpoint cp-001 --mode copy

# Apply to source project
smart_box apply --id task-001

# Discard the box
smart_box discard --id task-001

• Source Project: The original project directory. smart_box never modifies it directly.
• Box: An isolated execution space for one task or experiment.
• Checkpoint: A saved state inside a box, allowing rollback.
• Diff: Changes between the box's current state and a reference point.
• Patch: A portable changeset exported from a box for manual review and application.

smart_box <command> [options]

require "smart_box"

box = SmartBox::Box.create(
  source: ".",
  id: "task-001",
  mode: :copy,
  name: "fix bundler conflict"
)

result = box.run("bundle install")
box.checkpoint("after bundle install")
puts box.diff
box.rollback("cp-001")
box.export_patch("fix.patch")
box.apply(dry_run: true)

Copies the source project (excluding .git, node_modules, etc.) into an isolated workspace. Simple and works even if the source is not a git repository.

Uses git worktree add to create an isolated working directory. Faster for large projects and natively compatible with git workflows.

• Dangerous commands (rm -rf /, sudo, etc.) are blocked by default.
• All commands are restricted to the box workspace.
• The source project is never modified without explicit apply.
• All paths use absolute normalization to prevent path traversal.

• copy mode
• git-worktree mode
• Docker / DevContainer mode
• Command policy configuration
• Network policy
• Resource limits
• Concurrent boxes
• SmartExpert TUI integration
• SmartCoder workflow integration
• MCP tool wrapper
• JSON-RPC server mode