Skip to main content

​
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
Why it’s nice:
  • Omit --name to auto-generate a slug.
  • Keep secrets safe—values are obfuscated in output.
  • Pass --team-id if you need to charge a different workspace.
  • Add --yes to skip the confirmation prompt in automation.
  • GPUs? Coming soon. For now, leave off --gpu-count; the flag is ignored until GPU sandboxes launch.

​
Network Access

Sandboxes have outbound internet access enabled by default. For isolated environments (e.g., running untrusted code), disable it: 
# Create a sandbox without internet access
prime sandbox create python:3.11-slim --no-network-access

# Create with internet access (default behavior)
prime sandbox create python:3.11-slim --network-access
When network access is disabled:
  • Outbound connections to the internet are blocked
  • DNS resolution for internal services still works
  • Communication within the sandbox (e.g., sidecar) is allowed

​
Use Custom Docker Images

You can push your own Docker images to Prime’s registry and use them in sandboxes. Builds happen in the cloud, so you don’t need Docker running locally.

​
Push an Image

# Basic push (uses ./Dockerfile in current directory)
prime images push myapp:v1.0.0

# Specify a different Dockerfile
prime images push myapp:v1.0.0 --dockerfile custom.Dockerfile

# Use a different build context
prime images push myapp:v1.0.0 --context ./app
The CLI packages your build context, uploads it, and kicks off a remote build. You’ll get a build ID to track progress.

​
Check Build Status

# See all your images and their build status
prime images list
Status meanings:
  • Ready – Build succeeded, image is usable
  • Building – Build in progress
  • Pending – Queued for build
  • Failed – Build failed (check your Dockerfile)

​
Use Your Image

Once the status shows Ready, create a sandbox with it: 
prime sandbox create <user_id>/myapp:v1.0.0 --cpu-cores 2 --memory-gb 4

​
Delete an Image

prime images delete myapp:v1.0.0

# Skip confirmation
prime images delete myapp:v1.0.0 --yes

​
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)'"

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

​
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 HTTP services running inside your sandbox accessible from the internet.
Currently only HTTP is supported. TCP/UDP support is coming soon.
prime sandbox create python:3.11-slim --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
Works with Flask, FastAPI, Jupyter, or any HTTP service.

​
Clean Up in Bulk

# Delete a short list of sandboxes in one go
prime sandbox delete sbx_123 sbx_456 sbx_789

# Wipe every active sandbox (careful!)
prime sandbox delete --all --yes
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.