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. For VM sandboxes, set it to any negative value to remove the lifetime deadline. --idle-timeout-minutes terminates the sandbox sooner when nothing is using it, which is useful for agent workflows that might forget to clean up.

prime sandbox create python:3.11-slim \
  --timeout-minutes -1 \
  --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 be between 1 and 1,440 minutes. For a finite lifetime, it must not exceed --timeout-minutes.
SSH sessions do not count as activity.

When the sandbox terminates this way, its termination reason in prime sandbox get and on the dashboard reads Idle Timeout.

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.

Network Isolation

Sandboxes can restrict outbound traffic at creation time. Use an allowlist or a denylist — the two are mutually exclusive.

# 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. Each call replaces the whole list, and each flag takes a single comma-separated value:

# Replace the allowlist with two hosts
prime sandbox network sbx_123 --allow api.openai.com,*.example.com

# Replace the denylist; '*' blocks all outbound traffic
prime sandbox network sbx_123 --deny '*'

Rules can be saved but not yet active on the running sandbox. The CLI keeps retrying until they apply; check the current state with prime sandbox network <sandbox-id>.

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

prime sandbox run accepts --timeout <seconds> for the command itself, -w/--working-dir, and repeatable -e/--env KEY=VALUE overrides.

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 16 MiB per file. If a transfer complains about auth, run prime sandbox reset-cache and retry—the CLI refreshes the gateway token for you.

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 revoked and the key deleted on disconnect. OpenSSH (ssh) must be installed locally, and the sandbox must be RUNNING. By default you get a /bin/sh login shell, running as the sandbox’s default user in its working directory. To use a different shell installed in the image:

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

Anything after -- is passed straight to ssh, so you can run a single command instead of opening a shell:

prime sandbox ssh <sandbox-id> -- tail -f /workspace/train.log

Only interactive shells and remote commands are supported: port forwarding (-L/-R), agent forwarding, scp, and sftp are not. Use prime sandbox upload / download to move files. SSH sessions do not count as activity for the idle timeout, so a sandbox with an open SSH connection can still be shut down if you set --idle-timeout-minutes.

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

# Team admins: target one teammate's sandboxes
prime sandbox delete --all --user <user-id> --yes

You must use exactly one of: sandbox IDs, --label, or --all. --all and --label deletes run as a single server-side scoped delete: by default they cover your own sandboxes, --all-users covers the whole team, and --user <user-id> covers one teammate (both admin-only). The CLI prints a count preview before deleting, and per-sandbox results for explicit IDs. Need more ideas? Check the runnable scripts in prime/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

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

​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

SSH

Clean Up in Bulk

Quick Troubleshooting