CLI Reference

Sandbox CLI Reference

Last updated November 7, 2025

The Sandbox CLI, based on the Docker CLI, allows you to manage sandboxes, execute commands, copy files, and more from your terminal. This page provides a complete reference for all available commands.

Use the CLI for manual testing and debugging, or use the SDK to automate sandbox workflows in your application.

Installation

Install the Sandbox CLI globally to use all commands:

Terminal

pnpm i -g sandbox

You can invoke the CLI using the sandbox or sbx commands in your terminal.

Authentication

Terminal

sandbox login

`sandbox --help`

Get help information for all available sandbox commands:

terminal

sandbox <subcommand>

Description: Interfacing with Vercel Sandbox

Available subcommands:

list: List all sandboxes for the specified account and project. [alias: ls]
create: Create a sandbox in the specified account and project.
copy: Copy files between your local filesystem and a remote sandbox [alias: cp]
exec: Execute a command in an existing sandbox
ssh: Start an interactive shell in an existing sandbox
stop: Stop one or more running sandboxes [aliases: rm, remove]
run: Create and run a command in a sandbox
sh: Create and run an interactive shell in a new sandbox. [alias: shell]
login: Log in to the Sandbox CLI
logout: Log out of the Sandbox CLI

For more help, try running sandbox <subcommand> --help

`sandbox list`

List all sandboxes for the specified account and project.

terminal

sandbox list [OPTIONS]

Example

terminal

# 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

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.

Flags

Flag	Short	Description
`--all`	`-a`	Show all sandboxes, including stopped ones (we only show running ones by default).
`--help`	`-h`	Display help information.

`sandbox create`

Create a sandbox in the specified account and project.

terminal

sandbox create [OPTIONS]

Example

terminal

# Create a basic Node.js sandbox
sandbox create
 
# 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-app
 
# Create sandbox silently (no output)
sandbox create --silent

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.
`--runtime <runtime>`	-	Choose between Node.js ('node24' or 'node22') or Python ('python3.13'). We'll use Node.js 24 by default.
`--timeout <duration>`	-	How long the sandbox can run before we automatically stop it. Examples: '5m', '1h'. We'll stop it after 5 minutes by default.
`--publish-port <port>`	`-p`	Make a port from your sandbox accessible via a public URL.

Flags

Flag	Short	Description
`--silent`	-	Create the sandbox without showing you the sandbox ID.
`--help`	`-h`	Display help information.

`sandbox copy`

Copy files between your local filesystem and a remote sandbox.

terminal

sandbox copy [OPTIONS] <SANDBOX_ID:PATH> <SANDBOX_ID:PATH>

Example

terminal

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

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.

Flags

Flag	Short	Description
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`<SANDBOX_ID:PATH>`	The source file path (either a local file or sandbox_id:path for remote files).
`<SANDBOX_ID:PATH>`	The destination file path (either a local file or sandbox_id:path for remote files).

`sandbox exec`

Execute a command in an existing sandbox.

terminal

sandbox exec [OPTIONS] <sandbox_id> <command> [...args]

Example

terminal

# Execute a simple command in a sandbox
sandbox exec sb_1234567890 ls -la
 
# Run with environment variables
sandbox exec --env DEBUG=true sb_1234567890 npm test
 
# Execute interactively with sudo
sandbox exec --interactive --sudo sb_1234567890 sh
 
# Run command in specific working directory
sandbox exec --workdir /app sb_1234567890 python script.py

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.
`--workdir <directory>`	`-w`	Set the directory where you want the command to run.
`--env <key=value>`	`-e`	Set environment variables for your command.

Flags

Flag	Short	Description
`--sudo`	-	Run the command with admin privileges.
`--interactive`	`-i`	Run the command in an interactive shell.
`--tty`	`-t`	Enable terminal features for interactive commands.
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`<sandbox_id>`	The ID of the sandbox where you want to run the command.
`<command>`	The command you want to run.
`[...args]`	Additional arguments for your command.

`sandbox ssh`

Start an interactive shell in an existing sandbox.

terminal

sandbox ssh [OPTIONS] <sandbox_id>

Example

terminal

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

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.
`--workdir <directory>`	`-w`	Set the directory where you want the command to run.
`--env <key=value>`	`-e`	Set environment variables for your command.

Flags

Flag	Short	Description
`--sudo`	-	Run the command with admin privileges.
`--no-extend-timeout`	-	Do not extend the sandbox timeout while running an interactive command. Only affects interactive executions.
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`<sandbox_id>`	The ID of the sandbox where you want to start a shell.

`sandbox stop`

Stop one or more running sandboxes.

terminal

sandbox stop [OPTIONS] <sandbox_id> [...sandbox_id]

Example

terminal

# Stop a single sandbox
sandbox stop sb_1234567890
 
# Stop multiple sandboxes
sandbox stop sb_1234567890 sb_0987654321
 
# Stop sandbox for a specific project
sandbox stop --project my-app sb_1234567890

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.

Flags

Flag	Short	Description
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`<sandbox_id>`	The ID of the sandbox you want to stop.
`[...sandbox_id]`	Additional sandbox IDs to stop.

`sandbox run`

Create and run a command in a sandbox.

terminal

sandbox run [OPTIONS] <command> [...args]

Example

terminal

# Run a simple Node.js script
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
 
# Run with auto-cleanup
sandbox run --rm -- python3 script.py

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.
`--runtime <runtime>`	-	Choose between Node.js ('node24' or 'node22') or Python ('python3.13'). We'll use Node.js 24 by default.
`--timeout <duration>`	-	How long the sandbox can run before we automatically stop it. Examples: '5m', '1h'. We'll stop it after 5 minutes by default.
`--publish-port <port>`	`-p`	Make a port from your sandbox accessible via a public URL.
`--workdir <directory>`	`-w`	Set the directory where you want the command to run.
`--env <key=value>`	`-e`	Set environment variables for your command.

Flags

Flag	Short	Description
`--sudo`	-	Run the command with admin privileges.
`--interactive`	`-i`	Run the command in an interactive shell.
`--tty`	`-t`	Enable terminal features for interactive commands.
`--rm`	-	Automatically delete the sandbox when the command finishes.
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`<command>`	The command you want to run.
`[...args]`	Additional arguments for your command.

`sandbox sh`

Create and run an interactive shell in a new sandbox.

terminal

sandbox sh [OPTIONS] [...args]

Example

terminal

# Start an interactive shell in a new sandbox
sandbox sh
 
# Start a Node.js 22 sandbox and run a shell command
sandbox sh --runtime node22 -lc "node --version"

Options

Option	Alias	Description
`--token <token>`	-	Your Vercel authentication token. If you don't provide it, we'll use a stored token or prompt you to log in.
`--project <project>`	-	The project name or ID you want to use with this command.
`--scope <team>`	`--team`	The team you want to use with this command.
`--runtime <runtime>`	-	Choose between Node.js ('node24' or 'node22') or Python ('python3.13'). We'll use Node.js 24 by default.
`--timeout <duration>`	-	How long the sandbox can run before we automatically stop it. Examples: '5m', '1h'. We'll stop it after 5 minutes by default.
`--publish-port <port>`	`-p`	Make a port from your sandbox accessible via a public URL.
`--workdir <directory>`	`-w`	Set the directory where you want the command to run.
`--env <key=value>`	`-e`	Set environment variables for your command.

Flags

Flag	Short	Description
`--sudo`	-	Run the command with admin privileges.
`--no-extend-timeout`	-	Do not extend the sandbox timeout while running an interactive command. Only affects interactive executions.
`--rm`	-	Automatically remove the sandbox when the command finishes.
`--help`	`-h`	Display help information.

Arguments

Argument	Description
`[...args]`	Additional arguments for your command.

`sandbox login`

terminal

sandbox login

Example

terminal

# Log in to the Sandbox CLI
sandbox login

Flags

Flag	Short	Description
`--help`	`-h`	Display help information.

`sandbox logout`

Log out of the Sandbox CLI.

terminal

sandbox logout

Example

terminal

# Log out of the Sandbox CLI
sandbox logout

Flags

Flag	Short	Description
`--help`	`-h`	Display help information.

SDK Reference

Examples

Was this helpful?