iuv sandbox

iuv sandbox provides access to Cloudflare Sandbox for running isolated compute environments. Sandboxes are perfect for testing, building, and deploying applications in a secure, ephemeral environment.

List sandboxes

iuv sandbox list

Shows all your sandboxes with their status, runtime, and preview URLs.

Create a sandbox

# Create a basic Node.js sandbox
iuv sandbox create

# Create with custom configuration
iuv sandbox create --name my-app --runtime node24 --vcpus 4 --ports 3000,8080

# Create and clone a git repository
iuv sandbox create --git-url https://github.com/example/repo.git --git-revision main

# Create with environment variables
iuv sandbox create --env NODE_ENV=production,API_KEY=secret

Flag	Default	Description
-n, --name	auto-generated	Sandbox name
-r, --runtime	node24	Runtime environment (node24, node22, python3.13)
--vcpus	2	Number of vCPUs (1-8)
--ports	3000	Comma-separated ports to expose
--timeout	600000	Sleep timeout in milliseconds
-e, --env	-	Environment variables (KEY=value,KEY2=value2)
--git-url	-	Git repository URL to clone
--git-revision	-	Git revision to checkout
--app-id	-	Associated app ID

Get sandbox details

iuv sandbox get 123
iuv sandbox get 123 --json

Shows detailed information about a specific sandbox including:

• External sandbox ID
• Status (creating, running, sleeping, stopped, failed, destroyed)
• Runtime and resource configuration
• Preview URLs for exposed ports
• Creation and update timestamps

Delete a sandbox

iuv sandbox delete 123

Permanently deletes a sandbox and releases all associated resources.

Execute commands

# Run a command in the sandbox
iuv sandbox exec 123 "npm install"

# Run with custom working directory
iuv sandbox exec 123 "npm run build" --cwd /workspace/app

# Run with environment variables
iuv sandbox exec 123 "npm test" --env NODE_ENV=test

# Run in detached mode (fire-and-forget)
iuv sandbox exec 123 "npm start" --detached

Flag	Description
-e, --env	Environment variables (KEY=value,KEY2=value2)
--cwd	Working directory for the command
--detached	Run command in background mode

The command output is streamed to your terminal. The CLI exits with the same exit code as the remote command (unless running in detached mode).

Write files

# Upload a single file
iuv sandbox files 123 --file ./local-file.txt

# Upload multiple files
iuv sandbox files 123 --file ./file1.txt --file ./file2.txt

Files are uploaded to the sandbox’s /workspace directory. The filename is preserved (only the basename is used).

How it works

Sandboxes are backed by Cloudflare Sandbox, providing:

• Isolated environments: Each sandbox runs in its own secure container
• Fast startup: Sandboxes start in seconds, not minutes
• Automatic sleep: Sandboxes sleep after inactivity (configurable timeout)
• Port exposure: Exposed ports get unique preview URLs
• Git integration: Automatically clone repositories on creation

Use cases

Test a Node.js application

# Create sandbox and clone repo
iuv sandbox create --git-url https://github.com/myorg/myapp.git --name test-app

# Install dependencies and run tests
iuv sandbox exec <id> "npm install && npm test"

Quick API prototyping

# Create a Python sandbox
iuv sandbox create --runtime python3.13 --name api-proto

# Upload your script
iuv sandbox files <id> --file ./api.py

# Run the server
iuv sandbox exec <id> "python api.py" --detached

# Get the preview URL
iuv sandbox get <id>

Global options

All subcommands accept:

--api-base-url <url>   Override the API base URL (default: https://api.iuvdev.com)
--json                 Output machine-readable JSON

API Endpoints

The CLI uses these API endpoints internally:

• GET /v1/sandbox - List sandboxes
• POST /v1/sandbox - Create sandbox
• GET /v1/sandbox/:id - Get sandbox details
• DELETE /v1/sandbox/:id - Delete sandbox
• POST /v1/sandbox/:id/exec - Execute command
• POST /v1/sandbox/:id/files - Write files