sandbox

Isolated git experimentation using a disposable Docker container with branch isolation. Try out ideas, run scripts, refactor code, or let AI tools loose, all in a throwaway clone. When you're done, review the diff and decide whether to pull the branch back into your real repo.

Whether you're experimenting with a bold refactor, running an untrusted script, or giving an AI coding tool free rein, sandbox ensures your real repo stays untouched until you choose to merge.

Quick Start

npx @annnormanr/sandbox

No install required. Drops you into an interactive zsh shell (oh-my-zsh + powerlevel10k) inside the container. Docker or Podman required.

npx @annnormanr/sandbox -- npm test       # run a specific command
npx @annnormanr/sandbox --base develop -- npm test  # branch from develop

What You Get

• Git branch isolation: work happens on an isolated/ branch in a clone, never touching your real repo until you merge
• Hardened container: read-only rootfs, all capabilities dropped, no new privileges, pids-limited
• Host PATH available: commands from the host's PATH are mounted read-only into the sandbox by default, so tools like gh, python, rg, etc. just work. Disable with --no-path.
• Host filesystem stays read-only: even with host PATH mounted, the host's filesystem remains read-only — only the sandbox clone (/work) and /tmp are writable
• Push is physically impossible: no remote, config locked down, git remote helpers masked
• Persistent sandboxes: resume where you left off from an interactive menu of past sessions, scoped per repo
• Config overlay: drop files into .sandbox/ in your repo and they are shadowed into every sandbox clone, invisible to git
• Uncommitted changes guard: on exit, warns about unsaved work and offers to auto-commit or discard
• Review before merge: see exactly what changed, then merge, keep, or delete
• Cross-platform: runs on Linux and macOS. Windows users should run from WSL2.

Usage

sbx                                  interactive shell (zsh + oh-my-zsh)
sbx -- npm test                      run a specific command
sbx --base develop -- npm test       branch from a custom base ref
sbx --rebuild                        rebuild the sandbox Docker image
sbx --no-path                        disable host PATH mounting

Environment Variables

| Variable | Default | Description | | ----------------- | ---------------- | ------------------------------------------ | | SANDBOX_IMAGE | sandbox:latest | Docker image to use | | SANDBOX_NETWORK | host | Container network mode | | SANDBOX_MEMORY | 4g | Memory limit | | SANDBOX_CPUS | 2 | CPU limit | | SANDBOX_PIDS | 200 | Max processes | | SANDBOX_TIMEOUT | (none) | Hard wall-clock timeout (e.g. 30m, 1h) |

Workflow

1. Run sbx: your repo is cloned to .sandbox-cache/, an isolated branch is created, and you're dropped into a shell inside the container
2. Do your work: run tools, make commits, experiment freely
3. Exit the container: if you have uncommitted changes you'll be prompted to save or discard them, then a menu asks whether to merge the branch back, keep it for later, or delete everything
4. Your real repo was never touched until you chose to merge

Configuration Overlay

Drop files into .sandbox/ in your repo root and they are automatically shadowed into every sandbox clone. The files appear in the sandbox but are excluded from git tracking inside the clone, so they never show up as changes.

# Example: permissive Claude Code settings for sandbox use
mkdir -p .sandbox/.claude
cat > .sandbox/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": ["Bash(git *)", "Bash(npm *)", "Bash(node *)", "..."],
    "deny": ["Bash(git push*)", "Bash(git config*)"]
  }
}
EOF

Commit .sandbox/ to share config with your team, or keep it local. The overlay works for any file or tool, not just Claude Code.

Requirements

• Linux or macOS. Windows users must run from WSL2.
• Docker or Podman
• Git
• Node.js 18+

Install

npm install -g @annnormanr/sandbox
sbx

Or run on-demand with npx:

npx @annnormanr/sandbox