@stateset/sandbox-cli

Command-line interface for managing StateSet Sandbox environments — create sandboxes, manage checkpoints, upload artifacts, orchestrate agent sessions, and more.

Installation

npm install -g @stateset/sandbox-cli

Requires Node.js >= 20.

Quick Start

# Interactive setup — prompts for API key, URL, and defaults
stateset config setup

# Or configure manually
stateset config set-key sk_live_your_api_key
stateset config set-url https://api.stateset.com

# Create a sandbox and run a command
stateset sandbox create --timeout 600
stateset sandbox exec <sandbox-id> "echo hello world"

Configuration

The CLI stores configuration locally via conf. Environment variables take precedence over stored values.

| Setting | Env Variable | Default | |---------|-------------|---------| | API Key | STATESET_API_KEY | — | | API URL | STATESET_API_URL | http://localhost:8080 | | Default Timeout | STATESET_DEFAULT_TIMEOUT_SECONDS | 300 |

stateset config show      # Display current configuration
stateset config path      # Show config file location
stateset config clear     # Wipe all stored config

Commands

stateset sandbox

Manage sandbox environments.

stateset sandbox create [options]       # Create a new sandbox
stateset sandbox list                   # List all sandboxes
stateset sandbox get <id>               # Get sandbox details
stateset sandbox exec <id> <command>    # Execute a command
stateset sandbox stop <id>              # Stop a sandbox
stateset sandbox extend <id>            # Extend sandbox lifetime
stateset sandbox write <id> <path> <content>   # Write a file
stateset sandbox read <id> <path>              # Read a file
stateset sandbox ls-files <id>                 # List directory contents

Create options:

| Flag | Description | Example | |------|-------------|---------| | -t, --timeout <seconds> | Sandbox timeout | --timeout 600 | | -c, --cpus <cpus> | CPU limit | --cpus 1 | | -m, --memory <memory> | Memory limit | --memory 1Gi | | -i, --isolation <level> | Isolation level | --isolation gvisor | | -e, --env <KEY=VALUE> | Environment variables (repeatable) | -e FOO=bar -e BAZ=qux |

stateset checkpoint

Create, restore, and compare sandbox checkpoints.

stateset checkpoint create <sandbox-id> <name>    # Create checkpoint
stateset checkpoint list                           # List checkpoints
stateset checkpoint get <id>                       # Get details
stateset checkpoint restore <sandbox-id> <cp-id>   # Restore checkpoint
stateset checkpoint clone <id> <new-name>          # Clone a checkpoint
stateset checkpoint diff <id-1> <id-2>             # Compare two checkpoints
stateset checkpoint rm <id>                        # Delete checkpoint

Create options: --description, --include <paths>, --exclude <paths>, --no-env Restore options: --no-files, --no-env, --no-overwrite

stateset artifact

Upload, download, and manage sandbox artifacts.

stateset artifact upload <sandbox-id> <path>       # Upload artifact
stateset artifact list                              # List artifacts
stateset artifact get <id>                          # Get details
stateset artifact url <id>                          # Get download URL
stateset artifact download <sandbox-id> <id> <path> # Download artifact
stateset artifact rm <id>                           # Delete artifact

Upload options: --type <content-type>, --expires <seconds>, --metadata <key=value>

stateset session

Orchestrate long-running agent sessions with budget controls.

stateset session create [options]         # Create agent session
stateset session list                     # List sessions
stateset session get <id>                 # Get session details
stateset session start <id>              # Start session
stateset session pause <id>              # Pause session
stateset session resume <id>             # Resume session
stateset session stop <id>               # Stop gracefully
stateset session cancel <id>             # Cancel immediately
stateset session exec <id> <command>     # Execute in session
stateset session events <id>             # List session events

Create options:

| Flag | Description | |------|-------------| | -n, --name <name> | Session name | | -d, --description <desc> | Description | | --cost-cap <cents> | Cost cap in cents (e.g., 500 = $5) | | --iteration-limit <n> | Max iterations | | --duration-limit <seconds> | Max duration | | --cpus <cpus> | CPU allocation (default: 2) | | --memory <memory> | Memory allocation (default: 4Gi) |

stateset tunnel

Expose sandbox services via tunnels.

stateset tunnel open <sandbox-id>        # Create tunnel (default port 8080)
stateset tunnel list <sandbox-id>        # List active tunnels
stateset tunnel close <tunnel-id>        # Close tunnel

Open options: -p, --port <port>, --protocol <http|https>, --expires-in <seconds>

stateset pool

Monitor the warm pod pool.

stateset pool stats                      # Get pool statistics
stateset pool watch                      # Watch stats in real-time
stateset pool watch --interval 2         # Custom refresh interval

stateset deploy

Deploy to Kubernetes via cloud provider overlays.

stateset deploy aws                      # Deploy AWS overlay
stateset deploy gcp --dry-run            # Dry-run GCP overlay
stateset deploy azure --preflight --wait # Full deploy with checks

Options: --kubeconfig, --context, --namespace, --dry-run, --preflight, --wait, --smoke, --post-check

stateset doctor

Diagnose CLI configuration and API connectivity.

stateset doctor                          # Basic health check
stateset doctor --full                   # Deep diagnostics
stateset doctor --cluster                # Include Kubernetes checks
stateset doctor --api                    # Check dashboard endpoints

stateset health

Platform-wide health snapshot.

stateset health                          # Quick platform status
stateset health --grade                  # Include readiness grade
stateset health --cluster                # Include Kubernetes checks

stateset grade

Compute platform readiness grade (A+ through F).

stateset grade                           # Compute grade
stateset grade --minimum A-              # Fail if below A-
stateset grade --cluster --json          # Full check, JSON output

JSON Output

Most commands support --json for machine-readable output, useful for scripting:

stateset sandbox list --json | jq '.[0].id'
stateset pool stats --json
stateset grade --json

Development

cd cli
npm install
npm run dev -- sandbox list      # Run locally via tsx
npm run build                    # Compile TypeScript
npm test                         # Run tests
npm run typecheck                # Type-check without emitting

License

MIT