> ## Documentation Index > Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox CLI Guide > Command-line workflows for managing sandboxes ## Spin Up a Workspace ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} # 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 ## Custom Docker Images You can build and push custom Docker images to use in sandboxes. See the [Prime Images](/sandboxes/images) guide for details. ## Check In on Sandboxes ```bash theme={null} # 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: ```bash theme={null} # 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 ```bash theme={null} # 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: ```bash theme={null} prime sandbox create python:3.11-slim --name web-server # Returns sandbox ID, e.g. sbx_abc123 prime sandbox run "nohup python -m http.server 8000 --bind 0.0.0.0 > /dev/null 2>&1 &" prime sandbox expose 8000 --name web-server prime sandbox list-ports prime sandbox unexpose --yes ``` ### TCP Expose a raw TCP service and get a public `host:port` endpoint: ```bash theme={null} prime sandbox expose 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 ` to see both HTTP and TCP exposures along with their protocols and external ports. ## SSH Connect to a running sandbox with an interactive shell: ```bash theme={null} prime sandbox ssh ``` 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: ```bash theme={null} prime sandbox ssh --shell zsh ``` You can also forward ports through the SSH connection: ```bash theme={null} prime sandbox ssh -- -L 3000:localhost:3000 ``` ## Clean Up in Bulk ```bash theme={null} # 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.