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 named sandbox
sandbox create --name my-sandbox --image vercel/sandbox/node:24 --timeout 1h --publish-port 3000
 
# 2. Copy project files into the sandbox (sandbox copy transfers one file at a time)
tar -czf app.tgz -C ./my-app .
sandbox copy ./app.tgz my-sandbox:/tmp/app.tgz
sandbox exec my-sandbox -- sh -c "mkdir -p /app && tar -xzf /tmp/app.tgz -C /app"
 
# 3. Run commands inside the sandbox
sandbox exec --workdir /app my-sandbox -- npm install
sandbox exec --workdir /app my-sandbox -- npm run build
sandbox exec --workdir /app --env NODE_ENV=test my-sandbox -- npm test
 
# 4. Save the state as a snapshot for reuse
sandbox snapshot my-sandbox --stop
 
# 5. Create a new sandbox from the snapshot
sandbox create --snapshot <snapshot-id> --timeout 30m
 
# 6. Stop the current session (persistent sandboxes will resume on the next exec)
sandbox stop my-sandbox
 
# 7. Or permanently delete it
sandbox remove my-sandbox

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

sandbox create --image vercel/sandbox/node:24 --timeout 1h

This creates a Node.js 24 sandbox that auto-stops after one hour. The command outputs the sandbox ID. If you don't pass --image, the sandbox uses the default vercel/sandbox/universal image. The older --runtime flag is deprecated. Use --image instead.

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

sandbox create --image vercel/sandbox/node:24 --timeout 1h --publish-port 3000

For Python workloads:

sandbox create --image vercel/sandbox/python:3.14 --timeout 1h

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

sandbox create --image vercel/sandbox/node:24 --timeout 1h --connect

The sandbox copy command transfers one file at a time. To copy a single file into the sandbox:

sandbox copy ./my-app/package.json <name>:/app/package.json

To move a whole directory, archive it first and extract it inside the sandbox:

tar -czf app.tgz -C ./my-app .
sandbox copy ./app.tgz <name>:/tmp/app.tgz
sandbox exec <name> -- sh -c "mkdir -p /app && tar -xzf /tmp/app.tgz -C /app"

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

sandbox copy <name>:/app/output/results.json ./results.json

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

sandbox exec --workdir /app <name> -- npm install

sandbox exec --workdir /app <name> -- npm run build

To pass environment variables to the command:

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

For commands that need elevated permissions:

sandbox exec --sudo <name> -- sh -c "apt-get update && apt-get install -y jq"

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

sandbox connect <name>

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 <name> --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 --image vercel/sandbox/node:24 --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. Passing --allowed-domain creates a custom policy that only allows traffic to the listed destinations:

sandbox create --image vercel/sandbox/node:24 --timeout 1h --allowed-domain "*.npmjs.org" --allowed-domain "registry.npmjs.org"

To update the network policy of an existing sandbox:

sandbox config network-policy <name> --allowed-domain "api.example.com"

For a persistent sandbox, sandbox stop ends the current session and snapshots the filesystem. The sandbox can be resumed later by name. To delete it permanently, use sandbox remove.

# Stop the current session
sandbox stop <name>
 
# Stop multiple sandboxes
sandbox stop <name-1> <name-2>
 
# Permanently delete a sandbox and all its sessions
sandbox remove <name>

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