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

# Run Commands & SSH

> One-off commands, background jobs, and interactive shells

## Run a command

```bash CLI theme={null}
prime sandbox run sbx_123 --working-dir /workspace "python -c 'print(42)'"
```

```python Python theme={null}
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.

```python theme={null}
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](./lifecycle#timeouts) is long enough for the job, or set it negative for no deadline.

## SSH

Open an interactive shell in a running sandbox:

```bash theme={null}
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](./files) to move files.

> [!WARNING]
>
> SSH sessions do **not** count as activity for the [idle timeout](./lifecycle#timeouts), so a sandbox with an open SSH connection can still be shut down.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.