Sandbox CLI Reference

# List all running sandboxes
sandbox list
 
# List all sandboxes (including stopped ones)
sandbox list --all
 
# List sandboxes for a specific project
sandbox list --project my-nextjs-app
 
# Filter by name prefix and sort
sandbox list --name-prefix ci- --sort-by name --sort-order asc
 
# Filter by tag
sandbox list --tag env=staging --limit 100
 
# Page through results using the cursor reported by the previous page
sandbox list --cursor <token>

# Create a basic Node.js sandbox
sandbox create
 
# Create a sandbox with an explicit name
sandbox create --name my-sandbox
 
# Create a sandbox with 1 vCPU and open an interactive shell
sandbox create --vcpus 1 --connect
 
# Create a Python sandbox with custom timeout
sandbox create --runtime python3.13 --timeout 1h
 
# Create sandbox with port forwarding
sandbox create --publish-port 8080 --project my-project
 
# Create sandbox silently (no output)
sandbox create --silent
 
# Create sandbox from a snapshot
sandbox create --snapshot snap_abc123
 
# Create a non-persistent (ephemeral) sandbox
sandbox create --name ci-job --non-persistent
 
# Tag a sandbox at creation time
sandbox create --name my-sandbox --tag env=staging --tag team=infra
 
# Set snapshot expiration and retention
sandbox create --name my-sandbox --snapshot-expiration 7d --keep-last-snapshots 1
 
# Create sandbox without Internet access
sandbox create --network-policy deny-all
 
# Create sandbox with restricted Internet access (limited to Vercel's AI gateway)
sandbox create --allowed-domain ai-gateway.vercel.sh

# Fork with every supported field copied from the source
sandbox fork my-source
 
# Override the name and bump vCPUs; env vars must be re-supplied
sandbox fork my-source --name my-forked-sandbox --vcpus 4 --env FOO=1

# Inspect the current configuration of a sandbox
sandbox config list my-sandbox
 
# Update vCPUs and timeout
sandbox config vcpus my-sandbox 4
sandbox config timeout my-sandbox 30m
 
# Toggle persistence
sandbox config persistent my-sandbox false
 
# Update snapshot retention
sandbox config snapshot-expiration my-sandbox 14d
sandbox config keep-last-snapshots my-sandbox 1
 
# Replace the exposed port list
sandbox config ports my-sandbox -p 3000 -p 8000
 
# Clear all exposed ports
sandbox config ports my-sandbox
 
# Replace the tag set
sandbox config tags my-sandbox --tag env=production --tag team=infra
 
# Roll back to a previous snapshot
sandbox config current-snapshot my-sandbox snap_abc123
 
# Update the sandbox firewall to deny all egress traffic
sandbox config network-policy my-sandbox --network-policy deny-all
 
# Update the sandbox firewall to allow all egress traffic
sandbox config network-policy my-sandbox --mode allow-all
 
# Update the sandbox firewall to specific rules
sandbox config network-policy my-sandbox --allowed-domain vercel.com --allowed-domain ai-gateway.vercel.sh

# Copy file from local to sandbox
sandbox copy ./local-file.txt my-sandbox:/app/remote-file.txt
 
# Copy file from sandbox to local
sandbox copy my-sandbox:/app/output.log ./output.log
 
# Copy directory from sandbox to local
sandbox copy my-sandbox:/app/dist/ ./build/

# Execute a simple command in a sandbox
sandbox exec my-sandbox -- ls -la
 
# Run with environment variables
sandbox exec --env DEBUG=true my-sandbox -- npm test
 
# Execute interactively with sudo
sandbox exec --interactive --sudo my-sandbox -- sh
 
# Run command in specific working directory
sandbox exec --workdir /app my-sandbox -- python script.py
 
# Stop the current session after the command exits
sandbox exec --stop my-sandbox -- npm build

# Connect to an existing sandbox
sandbox connect my-sandbox
 
# Connect with a specific working directory
sandbox connect --workdir /app my-sandbox
 
# Connect with environment variables and sudo
sandbox connect --env DEBUG=true --sudo my-sandbox

# Stop a single sandbox
sandbox stop my-sandbox
 
# Stop multiple sandboxes
sandbox stop my-sandbox another-sandbox
 
# Stop sandbox for a specific project
sandbox stop --project my-project my-sandbox

# Delete a single sandbox
sandbox remove my-sandbox
 
# Delete multiple sandboxes
sandbox remove my-sandbox another-sandbox

# Run a simple Node.js script in a fresh sandbox
sandbox run -- node --version
 
# Run with custom environment and timeout
sandbox run --env NODE_ENV=production --timeout 10m -- npm start
 
# Run interactively with port forwarding
sandbox run --interactive --publish-port 3000 --tty -- npm run dev
 
# Resume an existing sandbox if it exists; otherwise create it
sandbox run --name my-sandbox -- npm test
 
# Stop the current session when the command exits
sandbox run --name my-sandbox --stop -- npm build
 
# Permanently delete the sandbox after the command exits
sandbox run --rm -- python3 script.py

# Create a snapshot of a running sandbox
sandbox snapshot my-sandbox --stop
 
# Create a snapshot that expires 14 days after its last use
sandbox snapshot my-sandbox --stop --expiration 14d
 
# Create a snapshot that never expires
sandbox snapshot my-sandbox --stop --expiration 0

# List snapshots for the current project
sandbox snapshots list
 
# List snapshots for a specific project
sandbox snapshots list --project my-project
 
# Filter snapshots by sandbox name
sandbox snapshots list --name my-sandbox
 
# Page through results
sandbox snapshots list --limit 50 --cursor <token>

# Get details of a specific snapshot
sandbox snapshots get snap_1234567890
 
# Get snapshot details for a specific project
sandbox snapshots get --project my-project snap_1234567890

# Delete a single snapshot
sandbox snapshots delete snap_1234567890
 
# Delete multiple snapshots for a specific project
sandbox snapshots delete --project my-project snap_1234567890 snap_0987654321

# Walk ancestors of the sandbox's current snapshot (default)
sandbox snapshots tree my-sandbox
 
# Walk descendants
sandbox snapshots tree my-sandbox --sort-order asc
 
# Continue from a specific snapshot
sandbox snapshots tree my-sandbox --cursor snap_abc123

# List running sessions
sandbox sessions list my-sandbox
 
# List all sessions (including stopped ones)
sandbox sessions list my-sandbox --all
 
# Sort and paginate
sandbox sessions list my-sandbox --sort-order asc --limit 100

# Log in to the Sandbox CLI
sandbox login

# Log out of the Sandbox CLI
sandbox logout