shift-cli sandbox
Manage isolated multi-agent sandbox sessions for shared development.
Usage
shift-cli sandbox <subcommand> [options]
Subcommands
create
Create a new sandbox session with isolated workspace, home, and tmp directories.
shift-cli sandbox create [--name <name>] [--owner <owner>]
| Option | Description |
|---|---|
--name <name> | Human-readable session name |
--owner <owner> | Owner identifier (API key/admin only) |
list
List sandbox sessions visible to the current user.
shift-cli sandbox list [--json]
push
Push a local directory into a sandbox session's workspace.
shift-cli sandbox push <session-id> <local-dir> [--remote-dir <path>]
| Option | Description |
|---|---|
--remote-dir <path> | Target directory in the sandbox (default: .) |
auth
Sync minimal local auth configuration (Claude or Codex) into the sandbox home directory.
shift-cli sandbox auth <session-id> <provider> [source]
| Argument | Description |
|---|---|
provider | Auth provider: claude or codex |
source | Optional source path for auth files |
exec
Run a shell command inside a sandbox session.
shift-cli sandbox exec <session-id> --cmd <command> [--cwd <path>] [--timeout <duration>]
| Option | Description |
|---|---|
--cmd <command> | Shell command to execute |
--cwd <path> | Working directory inside the sandbox |
--timeout <duration> | Timeout (e.g., 30s, 10m, 1h) |
rm
Remove a sandbox session and all its files.
shift-cli sandbox rm <session-id>
Session Layout
Each sandbox session provides:
<root>/
├── workspace/ # Shared codebase (push files here)
├── home/ # Agent home directory (~)
│ ├── .claude/ # Claude auth config (from sandbox auth)
│ └── .codex/ # Codex auth config (from sandbox auth)
└── tmp/ # Temporary files
Sessions are stored in /tmp/shift-platform/sandboxes (configurable via SHIFT_SANDBOX_ROOT).
Examples
# Create a session and push code
shift-cli sandbox create --name "pair-session" --json
shift-cli sandbox push sb_abc123 ./my-project
# Set up agent auth
shift-cli sandbox auth sb_abc123 claude
# Run tests in the sandbox
shift-cli sandbox exec sb_abc123 --cmd "bun test" --timeout 5m --json
# Clean up
shift-cli sandbox rm sb_abc123