Sandbox CLI Guide

Spin Up a Workspace

prime sandbox create python:3.11-slim \
  --name analytics-lab \
  --cpu-cores 2 \
  --memory-gb 4 \
  --disk-size-gb 20 \
  --timeout-minutes 240 \
  --env PROFILE=production \
  --secret DB_PASSWORD=hunter2

Why it’s nice:

Omit --name to auto-generate a slug.
Pass --team-id if you need to charge a different workspace.
Add --yes to skip the confirmation prompt in automation.

Idle Timeout

--timeout-minutes caps the total lifetime. --idle-timeout-minutes terminates the sandbox sooner when nothing is using it — useful for agent workflows that might forget to clean up.

prime sandbox create python:3.11-slim --container \
  --timeout-minutes 240 \
  --idle-timeout-minutes 15

The sandbox shuts itself down if no exec, upload, download, or file-read request lands within the idle window. Each new request resets the clock; long-running execs stay pinned for their full duration.

Disabled by default — set --idle-timeout-minutes to opt in.
Must satisfy 1 ≤ idle ≤ timeout and idle ≤ 1440.
SSH sessions do not count as activity yet, so a sandbox with an active SSH connection can still be reaped if you set an idle timeout.

When the sandbox terminates this way, its termination reason in prime sandbox get and on the dashboard reads Idle Timeout. Idle timeout is coming soon to VM sandboxes. Use --container for now.

Environment Variables & Secrets

Use --env for general configuration and --secret for sensitive values. Both accept KEY=VALUE format and can be specified multiple times.

prime sandbox create python:3.11-slim \
  --env APP_ENV=staging \
  --env LOG_LEVEL=debug \
  --secret API_KEY=sk-abc123 \
  --secret DB_PASSWORD=hunter2

Environment variables are stored in plain text and visible when you inspect the sandbox. Secrets are encrypted at rest and obfuscated in CLI output. Use them for API keys, passwords, database credentials, and anything else you wouldn’t want to appear in logs. Both are injected into the sandbox and accessible as standard environment variables at runtime.

Start Command

Pass a start command after -- to run your own process when the sandbox boots. There is no shell, so every argument must be its own token:

prime sandbox create python:3.11-slim -- python serve.py --port 8000

To get shell features (pipes, variables, &&), invoke a shell explicitly:

prime sandbox create python:3.11-slim -- /bin/sh -c "python serve.py --port 8000"

The start command is one-shot: when the process exits, the sandbox stops. Omit it to keep the sandbox up and ready for prime sandbox run. The legacy shell-string form, --start-command "python serve.py --port 8000", works only on container sandboxes (--container).

Network Isolation

Sandboxes can restrict outbound traffic at creation time. Use an allowlist or a denylist.

# Deny all egress, including DNS
prime sandbox create python:3.11-slim --network-deny 0.0.0.0/0

# Allow only specific destinations
prime sandbox create python:3.11-slim --network-allow api.openai.com

# Deny specific destinations, allow everything else
prime sandbox create python:3.11-slim --network-deny evil.example.com

Both flags are repeatable and accept domains (example.com, *.example.com) or IPv4 addresses/CIDRs; IPv6 is not supported. Update the rules on a running sandbox with prime sandbox network <sandbox-id> --allow ... / --deny .... Network isolation is not available on container sandboxes, which always have full outbound access.

Custom Docker Images

You can build and push custom Docker images to use in sandboxes. See the Prime Images guide for details.

Check In on Sandboxes

# Overview at a glance
prime sandbox list --status RUNNING --output table

# Rich details for one sandbox
prime sandbox get sbx_123 --output json

# Quick command to verify the runtime
prime sandbox run sbx_123 --working-dir /workspace "python -c 'print(42)'"

# Run as a specific user (username or UID, optionally USER:GROUP)
prime sandbox run sbx_123 --user agent "whoami"

# Capture logs for later debugging
prime sandbox logs sbx_123 > logs.txt

prime sandbox run --user is coming soon to VM sandboxes. Use --container for now.

Organize with Labels

Labels help you tag and manage groups of sandboxes:

# Create sandboxes with labels
prime sandbox create python:3.11-slim \
  --label experiment \
  --label ml-pipeline \
  --label team-research

# List sandboxes with specific labels (must have ALL labels)
prime sandbox list --label experiment --label ml-pipeline

# Delete all sandboxes with specific labels
prime sandbox delete --label experiment --yes

Labels are useful for:

Grouping related experiments or workflows
Tracking which team or project owns a sandbox
Bulk cleanup by category (dev, staging, test, etc.)

Move Files Around

# Push local assets into the sandbox
prime sandbox upload sbx_123 notebooks/analysis.ipynb /workspace/

# Pull results back home
prime sandbox download sbx_123 /workspace/report.csv reports/latest.csv

Note: File uploads are limited to 200MB per file. If a transfer complains about auth, run prime sandbox reset-cache and retry—the CLI refreshes the gateway token for you.

Expose Ports

Make services running inside your sandbox accessible from the internet. Both HTTP and TCP protocols are supported. Ports must be in the range 22–9000. Ports 8080, 2222, and 8081 cannot be exposed.

HTTP

Expose an HTTP service and get a public HTTPS URL:

prime sandbox create python:3.11-slim --container --name web-server
# Returns sandbox ID, e.g. sbx_abc123

prime sandbox run <sandbox-id> "nohup python -m http.server 8000 --bind 0.0.0.0 > /dev/null 2>&1 &"

prime sandbox expose <sandbox-id> 8000 --name web-server

prime sandbox list-ports <sandbox-id>

prime sandbox unexpose <sandbox-id> <exposure-id> --yes

HTTP exposure is coming soon to VM sandboxes. Use --container for now.

TCP

Expose a raw TCP service and get a public host:port endpoint:

prime sandbox expose <sandbox-id> 9000 --name tcp-server --protocol TCP

TCP exposures return an external_endpoint (host:port) and external_port instead of a URL. Connect using any TCP client. Use prime sandbox list-ports <sandbox-id> to see both HTTP and TCP exposures along with their protocols and external ports. TCP exposure is coming soon to VM sandboxes. Use --container for now.

SSH

Connect to a running sandbox with an interactive shell:

prime sandbox ssh <sandbox-id>

The CLI generates an ephemeral key pair, creates a session, and connects automatically. The session is cleaned up on disconnect. By default, the best available shell is auto-detected (bash > zsh > sh). To use a specific shell:

prime sandbox ssh <sandbox-id> --shell zsh

You can also forward ports through the SSH connection:

prime sandbox ssh <sandbox-id> -- -L 3000:localhost:3000

SSH is coming soon to VM sandboxes. Use --container for now.

Clean Up in Bulk

# Delete specific sandboxes by ID (space or comma-separated)
prime sandbox delete sbx_123 sbx_456 sbx_789

# Delete all sandboxes matching specific labels
prime sandbox delete --label experiment --label staging --yes

# Wipe every active sandbox (careful!)
prime sandbox delete --all --yes

# --all only deletes your own sandboxes by default.
# Use --all-users to include sandboxes from all team members.
prime sandbox delete --all --all-users --yes

You must use exactly one of: sandbox IDs, --label, or --all. Deletes are batched behind the scenes, and the CLI prints success/failure per sandbox so you can re-run failed IDs. Need more ideas? Check the runnable scripts in prime-cli/examples/ for CLI walkthroughs you can customize.

Quick Troubleshooting

Sandbox stuck in PROVISIONING? Wait a minute, then rerun prime sandbox list --status RUNNING. If it stays pending, delete and recreate from a known-good image.
Hitting auth issues? prime sandbox reset-cache refreshes the gateway token after you rotate API keys.

Getting Started

Lab

Libraries

Compute

Spin Up a Workspace

Idle Timeout

Environment Variables & Secrets

Start Command

Network Isolation

Custom Docker Images

Check In on Sandboxes

Organize with Labels

Move Files Around

Expose Ports

HTTP

TCP

SSH

Clean Up in Bulk

Quick Troubleshooting

​Spin Up a Workspace

​Idle Timeout

​Environment Variables & Secrets

​Start Command

​Network Isolation

​Custom Docker Images

​Check In on Sandboxes

​Organize with Labels

​Move Files Around

​Expose Ports

​HTTP

​TCP

​SSH

​Clean Up in Bulk

​Quick Troubleshooting

Spin Up a Workspace

Idle Timeout

Environment Variables & Secrets

Start Command

Network Isolation

Custom Docker Images

Check In on Sandboxes

Organize with Labels

Move Files Around

Expose Ports

HTTP

TCP

SSH

Clean Up in Bulk

Quick Troubleshooting