Sandbox CLI Reference

Use the Sandbox CLI to run coding agents, manage sandboxes, execute commands, and copy files from your terminal.

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

Sandboxes are identified by name (unique within your project) and are persistent by default: when stopped, the filesystem is snapshotted and restored on the next resume. Use sandbox remove to delete a sandbox permanently.

Install the Sandbox CLI globally to run sandbox or sbx from any directory:

pnpm i -g sandbox

yarn global add sandbox

npm i -g sandbox

bun add -g sandbox

You can also run the CLI without a global installation:

npx sandbox@latest --help

The CLI uses your saved Edgenivo credentials. If you aren't signed in, it starts the login flow when you run a command that requires authentication. Follow the verification link, or press Enter to open it in your browser.

You can also sign in explicitly:

sandbox login

Get help information for all available sandbox commands:

sandbox <subcommand>

Description: Interfacing with Edgenivo 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.
• fork: Fork an existing sandbox into a new one, inheriting its config and current snapshot.
• run: Create or resume a sandbox and run a command in it.
• exec: Execute a command in an existing sandbox.
• connect: Start an interactive shell in an existing sandbox. [aliases: ssh, shell]
• copy: Copy files between your local filesystem and a remote sandbox. [alias: cp]
• stop: Stop the current session of one or more sandboxes.
• extend: Add time to a running session without changing its default timeout.
• remove: Permanently delete one or more sandboxes and all their sessions.
• config: View and update sandbox configuration (resources, timeout, persistence, snapshot retention, network policy, drive mounts, tags).
• sessions: Inspect VM sessions for a sandbox.
• snapshot: Take a snapshot of the filesystem of a sandbox.
• snapshots: Manage sandbox snapshots.
• drives: Manage sandbox drives.
• login: Log in to the Sandbox CLI.
• logout: Log out of the Sandbox CLI.

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

List all sandboxes for the specified account and project.

sandbox list [OPTIONS]

# 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 sandbox in the specified account and project.

sandbox create [OPTIONS] [agent]

With Sandbox CLI 4.8.0 or later, use sandbox create <agent> in an interactive terminal to start a coding agent in a new sandbox:

sandbox create opencode

If you haven't installed the CLI globally, use npx sandbox@latest create opencode. The sbx alias also works with a global installation, for example sbx create pi.

The agent runs inside the sandbox, with its interactive interface in your local terminal. Its commands and file edits run remotely. Your local project files aren't uploaded automatically. Clone your repository inside the sandbox with appropriate credentials, or use sandbox copy to copy files.

Edgenivo login authenticates Sandbox access. Configure your chosen agent's credentials separately using its authentication flow or the --env option. The CLI tries to determine your team and project; set --scope and --project explicitly when needed:

sandbox create pi --name my-agent --scope my-team --project my-project

The CLI selects the universal image with the agents preinstalled. Omit --image, --runtime, and --snapshot when using an agent shortcut.

Exiting the agent leaves the sandbox running. Unless you pass --silent, the CLI prints commands to reconnect to the agent or stop the sandbox. Use the printed reconnect command to continue your conversation; running sandbox create <agent> again creates another sandbox. Before reconnecting, follow any reminder to export environment variables.

Stop the sandbox when you're finished. Normal Sandbox persistence settings apply.

# Create a basic Node.js sandbox
sandbox create
 
# Create a sandbox with an explicit name
sandbox create --name my-sandbox
 
# Create a sandbox on a Secure Compute network
sandbox create --name my-sandbox --network-id 3k9x7m2p5q8w1z4n
 
# 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 --image vercel/sandbox/python --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 sandbox in a specific region, with failover regions
sandbox create --region sfo1 --failover-regions iad1,cle1
 
# 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 Edgenivo's AI gateway)
sandbox create --allowed-domain ai-gateway.edgenivo.com
 
# Mount a drive with read-write access
sandbox create --mount cache:/data
 
# Mount a point-in-time, read-only snapshot of a drive
sandbox create --mount cache:/data:snapshot

A persistent sandbox snapshots its filesystem every time a session stops, so its snapshots accumulate over time. Use --keep-last-snapshots to keep only the N most recent. When a new snapshot brings the total above the limit, the oldest snapshots are no longer kept. The --delete-evicted-snapshots flag controls what happens to them: delete them immediately, or leave them to expire on their own.

• --keep-last-snapshots <count>: keep only the N most recent snapshots. count must be an integer from 1 to 10. This flag enables the retention policy, and the two flags below require it.
• --keep-last-snapshots-for <duration>: the expiration applied to the snapshots you keep, for example 7d or 30d. Use none or 0 for no expiration. When omitted, kept snapshots fall back to the sandbox's default snapshot expiration (--snapshot-expiration).
• --delete-evicted-snapshots <true|false>: what happens to a snapshot once it is no longer among the most recent kept ones. true (the default) deletes it immediately; false keeps it until its existing expiration instead.

Fork an existing sandbox into a new one. The fork is seeded from the source sandbox's current snapshot and inherits its config. Any option you pass overrides the copied value. If the source has no current snapshot, the fork falls back to creating a fresh sandbox with the source's image plus the copied config.

env is not copied (encrypted server-side); pass --env to set environment variables on the fork. Tags passed via --tag fully replace the source's tags (no per-key merge).

The fork runs in the source sandbox's region unless you pass --region. The fork also inherits the source's failover regions. Pass --failover-regions to replace them. If the source has a snapshot, that snapshot must be available in the target region.

The fork inherits the source's Secure Compute network unless you pass --network-id.

sandbox fork [OPTIONS] <source>

# 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

View and update sandbox configuration. Each subcommand updates one parameter; all parameters are also available together through the SDK's sandbox.update().

sandbox config <subcommand> <name> [VALUE | OPTIONS]

# Inspect the current configuration of a sandbox
sandbox config list my-sandbox
 
# Attach a Secure Compute network, or remove it from the next session
sandbox config network-id my-sandbox 3k9x7m2p5q8w1z4n
sandbox config network-id my-sandbox none
 
# 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 the failover regions
sandbox config failover-regions my-sandbox iad1,cle1
sandbox config failover-regions my-sandbox none
 
# 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 mounted drives for new sessions
sandbox config mounts my-sandbox --mount cache:/data --mount shared:/shared:snapshot
 
# Remove all drive mounts from new sessions
sandbox config mounts 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 edgenivo.com --allowed-domain ai-gateway.edgenivo.com

Copy a file between your local filesystem and a remote sandbox. The command transfers one file per invocation, and the destination is the full target path, not a directory.

sandbox copy [OPTIONS] <SOURCE> <DESTINATION>

# 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

Execute a command in an existing sandbox.

sandbox exec [OPTIONS] <name> -- <command> [...args]

# 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
 
# Kill the command if it runs longer than 30 seconds
sandbox exec --timeout 30s my-sandbox -- npm test
 
# Stop the current session after the command exits
sandbox exec --stop my-sandbox -- npm build

Start an interactive shell in an existing sandbox.

sandbox connect [OPTIONS] <name>

# 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 the current session of one or more sandboxes. For persistent sandboxes (the default), the filesystem is snapshotted first so the sandbox can be resumed later with the same name. To delete a sandbox permanently, use sandbox remove.

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

# 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

Add time to the current running session of a sandbox without changing its default timeout. The sandbox must have a running session. To change the timeout for future sessions, use sandbox config timeout.

sandbox extend [OPTIONS] <name> <duration>

# Add 30 minutes to the running session
sandbox extend my-sandbox 30m
 
# Add one hour
sandbox extend my-sandbox 1h

Permanently delete one or more sandboxes, along with all of their sessions. Once removed, a sandbox cannot be recovered. Use this instead of sandbox stop when you no longer need the sandbox at all.

Removing a sandbox keeps its snapshots by default, because several sandboxes can start from the same snapshot. Pass --delete-orphan-snapshots to also delete the sandbox's snapshots that no other sandbox uses, or delete them separately with sandbox snapshots delete.

sandbox remove [OPTIONS] <name> [...name]

# Delete a single sandbox
sandbox remove my-sandbox
 
# Delete multiple sandboxes
sandbox remove my-sandbox another-sandbox
 
# Delete a sandbox and its snapshots that no other sandbox uses
sandbox remove my-sandbox --delete-orphan-snapshots

Create (or resume) a sandbox and run a command in it. When --name matches an existing sandbox, the sandbox is resumed and any create-only flags are ignored.

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

# 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
 
# Run a command with a drive mounted for read-write access
sandbox run --mount cache:/data -- npm build
 
# Run a command with a point-in-time, read-only snapshot of a drive
sandbox run --mount cache:/data:snapshot -- ls /data

sandbox run accepts every option from sandbox create plus every option from sandbox exec. The most common are repeated below.

| --token <token> | - | Your Edgenivo authentication token. If you don't provide it, we'll use a stored token or prompt you to log in. |

Take a snapshot of the filesystem of a sandbox. Stops the sandbox automatically.

sandbox snapshot [OPTIONS] <name>

# 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

Manage sandbox snapshots.

sandbox snapshots <subcommand> [OPTIONS]

• list: List snapshots for the specified account and project. [alias: ls]
• get: Get details of a snapshot.
• delete: Delete one or more snapshots. [aliases: rm, remove]
• tree: Walk the snapshot ancestry tree for a sandbox.

List snapshots for the specified account and project.

sandbox snapshots list [OPTIONS]

# 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 snapshot.

sandbox snapshots get [OPTIONS] <snapshot_id>

# 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 one or more snapshots.

sandbox snapshots delete [OPTIONS] <snapshot_id> [...snapshot_id]

# 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 the snapshot ancestry tree starting from a sandbox's current snapshot. Snapshots form a parent → child tree whenever you create a sandbox from another snapshot.

sandbox snapshots tree [OPTIONS] <name>

# 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

Inspect VM sessions for a sandbox. A session represents one running VM instance of a sandbox; persistent sandboxes can have many sessions over time, separated by snapshots.

sandbox sessions <subcommand>

• list: List sessions for a sandbox. [alias: ls]

List sessions for a sandbox.

sandbox sessions list [OPTIONS] <name>

# 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

Drives are persistent storage that can be mounted into a sandbox. To learn more, see Drives.

sandbox drives <subcommand>

• list: List drives for the specified account and project. [alias: ls]
• get-or-create: Create a drive if it doesn't exist, or retrieve the existing drive.
• fork: Create a new drive from an existing drive's data.
• delete: Delete one or more drives. [aliases: rm, remove]

List drives for the specified account and project.

sandbox drives list [OPTIONS]

# List drives
sandbox drives list
 
# Filter drives by name and sort ascending
sandbox drives list --name-prefix cache- --sort-order asc
 
# Page through results using the cursor reported by the previous page
sandbox drives list --limit 100 --cursor <token>

Create a drive if it doesn't exist, or retrieve the existing drive with the same name.

sandbox drives get-or-create [OPTIONS] <name>

# Create or retrieve a drive with the default size of 1 TiB
sandbox drives get-or-create cache
 
# Create or retrieve a drive with a maximum size of 10 GiB
sandbox drives get-or-create cache --max-size 10737418240
 
# Create or retrieve a drive stored in the sfo1 region
sandbox drives get-or-create cache --region sfo1

Create a new drive from an existing drive's data. The fork belongs to the same project and inherits the source drive's region and maximum size. You can mount and update the fork independently of the source drive.

Use the source drive name and a new unique name for the fork:

sandbox drives fork [OPTIONS] <parent> <name>

Fork an existing cache drive:

sandbox drives fork cache cache-fork

Delete one or more drives. You can't delete a drive while it's attached to a sandbox.

sandbox drives delete [OPTIONS] <name> [...name]

# Delete one drive
sandbox drives delete cache
 
# Delete multiple drives
sandbox drives delete cache build-artifacts

Log in to the Sandbox CLI.

sandbox login

# Log in to the Sandbox CLI
sandbox login

Log out of the Sandbox CLI.

sandbox logout

# Log out of the Sandbox CLI
sandbox logout

Create a sandbox and run a command in one step:

sandbox run echo "Hello Sandbox!"

You'll see output like:

For interactive work, create a named sandbox that stays running:

sandbox create --name my-sandbox --timeout 30m

sandbox create prints the sandbox's name. Use that name to interact with the sandbox. Because persistent sandboxes can be resumed, you can also reconnect later by running sandbox exec my-sandbox -- ... or sandbox connect my-sandbox.

Run commands using the sandbox name:

# Check the environment
sandbox exec my-sandbox -- node --version
 
# Install packages
sandbox exec my-sandbox -- npm init -y
sandbox exec my-sandbox -- npm install express
 
# Create files
sandbox exec my-sandbox -- touch server.js

Test local code in the sandbox:

# Copy your code to the sandbox
sandbox copy ./my-app.js my-sandbox:/home/sandbox/my-app.js
 
# Run it
sandbox exec my-sandbox -- node /home/sandbox/my-app.js
 
# Copy results back
sandbox copy my-sandbox:/home/sandbox/output.json ./results.json

Work inside the sandbox like it's your machine:

sandbox exec --interactive --tty my-sandbox -- bash

Now you're inside the sandbox! Try:

pwd                    # See where you are
ls -la                 # List files
node -e "console.log('Inside!')"  # Run Node.js
exit                   # Leave when done

When finished:

sandbox stop my-sandbox

# Create a named sandbox
NAME=$(sandbox create --name "ai-test-$(date +%s)" --timeout 15m --silent)
 
# Copy AI-generated code
sandbox copy ./ai-generated.js $NAME:/app/
 
# Test it interactively
sandbox exec --interactive --tty $NAME -- bash
# Now inside: cd /app && node ai-generated.js
 
# Clean up (remove permanently)
sandbox remove $NAME

# Create a named sandbox with more time
sandbox create --name debug-build --timeout 1h
 
# Copy your project
sandbox copy ./my-project/ debug-build:/app/
 
# Try building
sandbox exec --workdir /app debug-build -- npm run build
 
# If it fails, debug interactively
sandbox exec -it debug-build -- bash

# Create with port exposure
sandbox create --name dev --timeout 30m --publish-port 3000
 
# Start your dev server
sandbox exec --workdir /app dev -- npm run dev
 
# Access at the provided URL (printed by `sandbox create`)
# Visit: https://<random-id>.vercel.run