Running commands in a Vercel Sandbox

Use this guide to create isolated sandbox environments for running commands, builds, and tests. You'll create a sandbox, execute commands, copy files in and out, and save snapshots for reuse.

Use this block when you already know what you're doing and want the full command sequence. Use the steps below for context and checks.

# 1. Create a sandbox
sandbox create --runtime node24 --timeout 1h --publish-port 3000
 
# 2. Copy project files into the sandbox
sandbox cp ./my-app/. <sandbox-id>:/app
 
# 3. Run commands inside the sandbox
sandbox exec --workdir /app <sandbox-id> "npm install"
sandbox exec --workdir /app <sandbox-id> "npm run build"
sandbox exec --workdir /app --env NODE_ENV=test <sandbox-id> "npm test"
 
# 4. Save the state as a snapshot for reuse
sandbox snapshot <sandbox-id> --stop
 
# 5. Create a new sandbox from the snapshot
sandbox create --snapshot <snapshot-id> --timeout 30m
 
# 6. Clean up
sandbox stop <sandbox-id>

Create a new sandbox environment with the runtime and configuration you need:

sandbox create --runtime node24 --timeout 1h

This creates a Node.js 24 sandbox that auto-stops after one hour. The command outputs the sandbox ID.

To make a port accessible via a public URL (useful for testing web applications):

sandbox create --runtime node24 --timeout 1h --publish-port 3000

For Python workloads:

sandbox create --runtime python3.13 --timeout 1h

To create a sandbox and immediately connect to an interactive shell:

sandbox create --runtime node24 --timeout 1h --connect

Copy your project files into the sandbox:

sandbox cp ./my-app/. <sandbox-id>:/app

You can also copy files out of the sandbox back to your local machine:

sandbox cp <sandbox-id>:/app/output/results.json ./results.json

Execute commands inside the sandbox. Use --workdir to set the working directory:

sandbox exec --workdir /app <sandbox-id> "npm install"

sandbox exec --workdir /app <sandbox-id> "npm run build"

To pass environment variables to the command:

sandbox exec --workdir /app --env NODE_ENV=test <sandbox-id> "npm test"

For commands that need elevated permissions:

sandbox exec --sudo <sandbox-id> "apt-get update && apt-get install -y jq"

For exploratory work or debugging, connect to the sandbox interactively:

sandbox connect <sandbox-id>

This opens a shell session inside the sandbox. Exit the shell to disconnect.

After setting up a sandbox with dependencies installed and configured, save it as a snapshot so you can recreate the same environment later:

sandbox snapshot <sandbox-id> --stop

Snapshotting always stops the sandbox automatically. The --stop flag confirms you acknowledge this behavior.

To list your saved snapshots:

sandbox snapshots list

Recreate an environment from a saved snapshot:

sandbox create --snapshot <snapshot-id> --timeout 30m

This starts a new sandbox with all the files, dependencies, and configuration from the snapshot already in place.

For simple tasks where you don't need to manage the sandbox lifecycle, use sandbox run. This creates a sandbox, runs a command, and optionally cleans up:

sandbox run --runtime node24 --rm -- node -e 'console.log(process.version)'

The --rm flag automatically deletes the sandbox after the command finishes.

Control what network resources the sandbox can reach:

sandbox create --runtime node24 --timeout 1h --network-policy deny-all --allowed-domain "*.npmjs.org" --allowed-domain "registry.npmjs.org"

To update the network policy of an existing sandbox:

sandbox config network-policy <sandbox-id> --network-policy deny-all --allowed-domain "api.example.com"

Stop and remove a sandbox when you're done:

sandbox stop <sandbox-id>

To stop multiple sandboxes:

sandbox stop <sandbox-id-1> <sandbox-id-2>

To see all running sandboxes:

sandbox list

To include stopped sandboxes:

sandbox list --all

Remove snapshots you no longer need to keep your environment clean:

sandbox snapshots delete <snapshot-id>

• Sandbox CLI reference
• Vercel Sandbox overview