Run Commands & SSH

Run a command

prime sandbox run sbx_123 --working-dir /workspace "python -c 'print(42)'"

result = client.execute_command(sandbox.id, "python -c 'print(42)'")
print(result.stdout, result.stderr, result.exit_code)

Responses include stdout, stderr, and exit code. Options:

Option	CLI	Python
Timeout (seconds)	`--timeout`	`timeout` (default 300)
Working directory	`-w` / `--working-dir`	—
Extra env vars	`-e` / `--env KEY=VALUE`	`env={"KEY": "VALUE"}`

A command that exceeds its timeout raises CommandTimeoutError in the SDK. For work that should outlive the request, use a background job.

Background jobs

Background jobs keep running in the sandbox, independent of the command connection, while you poll for completion. They persist until they finish or the sandbox terminates.

import time

sandbox = client.create(
    CreateSandboxRequest(
        name="training-job",
        docker_image="python:3.11-slim",
        timeout_minutes=1440,  # 24 hours
        cpu_cores=4,
        memory_gb=16,
    )
)
client.wait_for_creation(sandbox.id)

job = client.start_background_job(sandbox.id, "python train.py --epochs 100")

while True:
    status = client.get_background_job(sandbox.id, job)
    if status.completed:
        print(status.exit_code, status.stdout)
        break
    time.sleep(30)

client.download_file(sandbox.id, "/app/model.pt", "./model.pt")
client.delete(sandbox.id)

Make sure the sandbox timeout is long enough for the job, or set it negative for no deadline.

SSH

Open an interactive shell in a running sandbox:

prime sandbox ssh <sandbox-id>

# Use a different shell installed in the image
prime sandbox ssh <sandbox-id> --shell bash

# Anything after -- goes straight to ssh, e.g. one remote command
prime sandbox ssh <sandbox-id> -- tail -f /workspace/train.log

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 as the sandbox’s default user in its working directory. Only interactive shells and remote commands are supported: port forwarding (-L/-R), agent forwarding, scp, and sftp are not. Use file transfers 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.

Getting Started

Inference

Model Factory

Community

Compute

Traces

Libraries

Run a command

Background jobs

SSH

​Run a command

​Background jobs

​SSH

Run a command

Background jobs

SSH