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 \
  --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.

​
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 container and accessible as standard environment variables at runtime.

​
Start Command

By default, sandboxes run tail -f /dev/null to keep the container alive for interactive use. Use --start-command to override this with your own entrypoint: 
prime sandbox create python:3.11-slim \
  --start-command "python serve.py --port 8000"
This replaces the image’s ENTRYPOINT, so make sure your command is the full process you want running. If you omit --start-command, the default keeps the sandbox idle and ready for prime sandbox run commands.

​
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 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 --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

​
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.

​
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

​
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.