SDK
CLI Reference

CodeSandbox SDK CLI

The CodeSandbox SDK provides a command-line interface (CLI) called csb for managing sandboxes, templates, and configurations.

Installation

npm install @codesandbox/sdk

Direct Usage with npx

You can also use the CLI directly without installing it by using npx:

npx @codesandbox/sdk <command> [options]

This is useful for one-time usage or when you don't want to install the package globally.

Authentication

The CLI requires authentication with a CodeSandbox API token. You can obtain one from https://codesandbox.io/t/api (opens in a new tab).

Set your API token using the CSB_API_KEY environment variable:

export CSB_API_KEY=your_api_token_here

Usage

Basic Usage

csb <command> [options]

Interactive Dashboard

Running csb without any arguments launches an interactive dashboard:

csb

This provides a visual interface for managing your sandboxes and templates, including advanced debugging capabilities.

Interactive Debugging Features

The interactive dashboard includes comprehensive debugging tools:

Terminal Access

  • Full terminal interface - Access bash shell in any running sandbox
  • Real-time interaction - Type commands and see live output
  • Standard terminal features - Supports Ctrl+C, tab completion, arrow keys
  • History scrolling - Navigate output with SHIFT + ↑/↓
  • Easy access - Select sandbox → choose "Terminal" from actions menu

Resource Monitoring

  • VM usage tracking - View running VMs vs. account limits
  • Resource specifications - Monitor CPU, memory, and storage usage
  • Activity timestamps - See when VMs were last active
  • Session information - Track when sandbox sessions started

Sandbox Management

  • Lifecycle controls - Start, hibernate, shutdown, restart sandboxes
  • Visual status indicators - Quickly identify running vs. hibernated sandboxes
  • Batch operations - Manage multiple sandboxes efficiently

Commands

build

Build an efficient memory snapshot from a directory that can be used to create sandboxes quickly.

The build command now provides enhanced logging for container operations, showing real-time progress during Docker builds and container startup with live log previews.

Syntax:

csb build <directory> [options]

Arguments:

  • <directory> - Path to the project directory to create a snapshot from (required)

Options:

  • --from-sandbox <id> - Use and update an existing sandbox as a template
  • --name <name> - Name for the resulting sandbox that will serve as snapshot
  • --ports <ports...> - Ports to wait for to open before creating snapshot (array of numbers)
  • --vm-tier <tier> - Base specs to use for the template sandbox (choices: micro, small, medium, large, xlarge)
  • --vm-build-tier <tier> - Specs to use for building the template sandbox (choices: micro, small, medium, large, xlarge)
  • --alias <alias> - Alias that should point to the created template. Format: namespace@alias or just alias
  • --ci - CI mode, will exit process if any error occurs (default: false)
  • --log-path <path> - Relative path to log file, if any

Examples:

# Build a template from current directory
csb build .
 
# Build with custom name and alias
csb build ./my-project --name "My Template" --alias my-template
 
# Build with specific VM tiers and ports
csb build ./web-app --vm-tier small --vm-build-tier medium --ports 3000 8080
 
# Build in CI mode
csb build ./project --ci

sandboxes

Manage sandboxes with various subcommands.

sandboxes list

List sandboxes with filtering and formatting options.

Syntax:

csb sandboxes list [options]

Options:

  • --output, -o <fields> - Output format (comma-separated list of fields: id,title,privacy,tags,createdAt,updatedAt)
  • --headers - Show headers (default: true)
  • --tags, -t <tags> - Filter by tags (comma-separated)
  • --status, -s <status> - Filter by status (choices: running)
  • --page, -p <number> - Page number
  • --page-size <number> - Number of items per page
  • --since <date> - Filter by creation date
  • --order-by <field> - Order results by field (choices: inserted_at, updated_at)
  • --direction <dir> - Sort direction (choices: asc, desc)
  • --limit, -l <number> - Maximum number of sandboxes to list (default: 100)

Examples:

# List all sandboxes
csb sandboxes list
 
# List running sandboxes with custom output
csb sandboxes list --status running --output id,title,createdAt
 
# List sandboxes with specific tags
csb sandboxes list --tags template,nodejs
 
# List recent sandboxes
csb sandboxes list --since 2024-01-01 --order-by inserted_at --direction desc

sandboxes fork

Fork an existing sandbox.

Syntax:

csb sandboxes fork <id>

Arguments:

  • <id> - ID of the sandbox to fork (required)

Example:

csb sandboxes fork abc123

sandboxes hibernate

Hibernate sandbox(es) to save resources.

Syntax:

csb sandboxes hibernate [id]

Arguments:

  • [id] - ID of the sandbox to hibernate (optional - if not provided, reads from stdin)

Examples:

# Hibernate specific sandbox
csb sandboxes hibernate abc123
 
# Hibernate multiple sandboxes via stdin
echo "abc123\ndef456" | csb sandboxes hibernate

sandboxes shutdown

Shutdown sandbox(es) completely.

Syntax:

csb sandboxes shutdown [id]

Arguments:

  • [id] - ID of the sandbox to shutdown (optional - if not provided, reads from stdin)

Examples:

# Shutdown specific sandbox
csb sandboxes shutdown abc123
 
# Shutdown multiple sandboxes via stdin
echo "abc123\ndef456" | csb sandboxes shutdown

host-tokens

Manage host tokens for sandbox access.

host-tokens list

List host tokens for a sandbox.

Syntax:

csb host-tokens list <sandbox-id>

Arguments:

  • <sandbox-id> - ID of the sandbox (required)

Example:

csb host-tokens list abc123

host-tokens create

Create a host token for a sandbox.

Syntax:

csb host-tokens create <sandbox-id> --expires-at <date>

Arguments:

  • <sandbox-id> - ID of the sandbox (required)

Options:

  • --expires-at, -e <date> - Expiration date (ISO 8601 format, e.g. 2024-12-31T23:59:59Z) (required)

Example:

csb host-tokens create abc123 --expires-at 2024-12-31T23:59:59Z

host-tokens update

Update the expiration date of a host token.

Syntax:

csb host-tokens update <sandbox-id> <host-token-id> [--expires-at <date>]

Arguments:

  • <sandbox-id> - ID of the sandbox (required)
  • <host-token-id> - ID of the host token (required)

Options:

  • --expires-at, -e <date> - Expiration date (ISO 8601 format) or omit to remove expiration

Example:

csb host-tokens update abc123 token456 --expires-at 2024-12-31T23:59:59Z

host-tokens revoke

Revoke host token(s).

Syntax:

csb host-tokens revoke <sandbox-id> [host-token-id] [--all]

Arguments:

  • <sandbox-id> - ID of the sandbox (required)
  • [host-token-id] - ID of the host token (optional)

Options:

  • --all, -a - Revoke all preview tokens (conflicts with host-token-id)

Examples:

# Revoke specific token
csb host-tokens revoke abc123 token456
 
# Revoke all tokens
csb host-tokens revoke abc123 --all

preview-hosts

Manage preview hosts that can access the Preview API.

preview-hosts list

List current preview hosts.

Syntax:

csb preview-hosts list

preview-hosts add

Add a preview host.

Syntax:

csb preview-hosts add <host>

Arguments:

  • <host> - Host to add (required)

Example:

csb preview-hosts add example.com

preview-hosts remove

Remove a preview host.

Syntax:

csb preview-hosts remove <host>

Arguments:

  • <host> - Host to remove (required)

Example:

csb preview-hosts remove example.com

preview-hosts clear

Clear all preview hosts.

Syntax:

csb preview-hosts clear

Enhanced Logging

Container Build Logging

The build command provides enhanced visibility during container operations:

  • Real-time progress updates - Shows live output from Docker builds
  • Container startup monitoring - Displays current log lines during container initialization
  • Log previews - Shows condensed versions of long log lines (up to 100 characters)
  • Step-by-step tracking - Clear indication of which setup step is running

Example output during build:

Building and starting container (RUN npm install --production)...
Building and starting container (Successfully installed dependencies)...

Error Handling

The CLI provides detailed error messages and logs. For build operations, logs are automatically saved to files when errors occur:

  • Setup failure logs: setup-failure-{sandbox-id}-{timestamp}.log
  • Use --log-path option to specify custom log directory

Exit Codes

  • 0 - Success
  • 1 - Error occurred

Environment Variables

  • CSB_API_KEY - CodeSandbox API token (required)

Configuration

The CLI automatically detects your API key from the CSB_API_KEY environment variable. Make sure to set this before using any commands.

Tips

  1. Use the interactive dashboard (csb without arguments) for a visual overview
  2. Use --ci flag in build commands for automated environments
  3. Combine commands with shell pipes for batch operations
  4. Use --output option to customize list formatting for scripting
  5. Set appropriate VM tiers based on your resource needs
Preview API AccessTemplate Library