| name | sandbox |
| description | Run project commands (build, test, lint) in a cloud sandbox with common runtimes and on-demand toolchains. |
When to use
Use sandbox to run project commands: builds, tests, lints, and anything that needs runtimes not available locally (Java, Python, etc.). The sandbox auto-creates on first use, syncs your worktree, and stops automatically when idle.
For technical browser orchestration guidance โ choosing between existing UI automation, lightweight interaction, deterministic visible capture, verification, and artifact patterns โ use the dedicated browser skill. Keep app-specific browser flows in repo runbooks or task prompts.
Usage
Supported forms:
sandbox <command> [args...]
sandbox bash -c '<command>'
sandbox bash -lc '<command>'
sandbox sh -c '<command>'
sandbox sh -lc '<command>'
Examples:
sandbox mvn test -pl module-auth
sandbox ./gradlew build
sandbox bash -c 'make build && make test'
sandbox npm test
For a single command, write it naturally: sandbox mvn test -pl module-auth.
For shell chaining, pipelines, or redirects, wrap the command explicitly:
sandbox bash -c 'make build && make test'
sandbox bash -c 'npm run build && npm test'
How it works
- On first run, a cloud sandbox is created for the current worktree
- Before exec, committed and uncommitted worktree changes are uploaded; sync is skipped if more than 100 files are dirty
- The command runs inside the sandbox and output streams back in real time
- After a successful command, created or modified files are pulled back to your worktree
- Sandbox auto-stops after 15 minutes idle
Workflow
cd /workspace/worktrees/myrepo/feat/auth
sandbox mvn test -pl module-auth
sandbox mvn test -pl module-auth
sandbox ./gradlew spotlessCheck
Pre-installed runtimes
The sandbox image is intentionally slim. Preinstalled by default:
- Node: 22 (default), 20 via nvm. pnpm available via corepack.
- Java: 21 (default), 17 (Temurin) via SDKMAN. Maven and Gradle included.
- Python: 3.12 (default) via pyenv.
uv available for fast installs.
- PHP: 8.4 (default) via
ondrej/php, with common CLI extensions installed.
- Docker: Docker CE with docker compose. Start the daemon with
sudo dockerd & before use.
- Browser automation/recording:
agent-browser with Chrome for Testing preinstalled, plus ffmpeg, xvfb, xdotool, tree, and ImageMagick (identify, convert, compare).
Browser examples:
sandbox agent-browser --session qa open https://example.com
sandbox agent-browser --session qa screenshot /tmp/example.png
sandbox identify /tmp/example.png
sandbox xvfb-run -a agent-browser --session qa open https://example.com --headed
Install less-common toolchains on demand per task by running the appropriate
installer inside the sandbox (for example via nvm, pyenv, rustup, or by
downloading a release tarball into $HOME/.local). Use sandbox bash -lc '...'
to run install commands, then invoke the toolchain the same way.
To use a non-default version, either set it permanently or inline it with your command:
sandbox sdk default java 17.0.18-tem
sandbox mvn test
sandbox bash -c 'sdk use java 17.0.18-tem && mvn test'
sandbox bash -c 'nvm use 20 && npm test'
Notes
- Each worktree gets its own isolated sandbox โ switching worktrees creates a separate sandbox
- Code is synced to
/workspace/sandbox inside the sandbox โ paths in error output will show this prefix
- Subsequent runs reuse the sandbox for the same worktree
- Multiple
sandbox commands on the same worktree can run in parallel