### Development Setup for Prime MCP Server

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-mcp-server/README.md

Commands for cloning the repository, installing dependencies, running tests, and linting the code.

```bash
# Clone the repo
git clone https://github.com/PrimeIntellect-ai/prime.git
cd prime/packages/prime-mcp-server

# Install dependencies
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check .
```

--------------------------------

### Install Prime using uv

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Installs the Prime CLI using the uv package manager. Ensure uv is installed first.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
uv tool install prime
```

--------------------------------

### Install Prime CLI

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Installs the Prime CLI using `uv` (recommended) or `pip`. The `prime-sandboxes` package is available for SDK-only installation.

```bash
# Install
uv tool install prime          # recommended
pip install prime              # alternative
pip install prime-sandboxes    # sandboxes SDK only (~50 KB)
```

--------------------------------

### Install prime-sandboxes SDK

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Install the SDK using uv or pip. This is the first step to using the Prime Sandboxes functionality.

```bash
uv pip install prime-sandboxes
```

```bash
pip install prime-sandboxes
```

--------------------------------

### Install Prime CLI using uv

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Installs the Prime CLI using the uv package manager. Ensure uv is installed first.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install prime
uv tool install prime
```

--------------------------------

### Install Environments from Hub

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Installs environments from the hub, defaulting to `uv` for package management. Supports installing specific versions and batch installations.

```bash
prime env install openai/gsm8k
prime env install openai/gsm8k@0.2.1 --with pip
prime env install env1 env2 env3
```

--------------------------------

### Install Prime using pip

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Installs the Prime CLI using pip.

```bash
pip install prime
```

--------------------------------

### Install Prime Evals SDK

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-evals/README.md

Install the Prime Evals SDK using uv or pip.

```bash
uv pip install prime-evals
```

```bash
pip install prime-evals
```

--------------------------------

### Prime CLI - Installation and Authentication

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Commands for installing the Prime CLI, authenticating, and configuring settings.

```APIDOC
## CLI Reference — Key Commands

### Installation and authentication

```bash
# Install
uv tool install prime          # recommended
pip install prime              # alternative
pip install prime-sandboxes    # sandboxes SDK only (~50 KB)

# Auth
prime login                    # interactive (stores key in ~/.prime/config.json)
prime config set-api-key       # interactive key prompt
export PRIME_API_KEY="sk-..."  # environment variable

# Configuration
prime config view
prime config set-ssh-key-path ~/.ssh/id_rsa.pub

# Team context
prime teams list
prime switch                   # interactive picker
prime switch my-team-slug
prime switch personal
```
```

--------------------------------

### Quick Start: Synchronous Sandbox Operations

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Initialize the API client, create a sandbox, wait for it to be ready, execute a command, and then delete the sandbox. Ensure you replace 'your-api-key' with your actual API key.

```python
from prime_sandboxes import APIClient, SandboxClient, CreateSandboxRequest

# Initialize
client = APIClient(api_key="your-api-key")
sandbox_client = SandboxClient(client)

# Create a sandbox
request = CreateSandboxRequest(
    name="my-sandbox",
    docker_image="python:3.11-slim",
    cpu_cores=2,
    memory_gb=4,
)

sandbox = sandbox_client.create(request)
print(f"Created: {sandbox.id}")

# Wait for it to be ready
sandbox_client.wait_for_creation(sandbox.id)

# Execute commands
result = sandbox_client.execute_command(sandbox.id, "python --version")
print(result.stdout)

# Clean up
sandbox_client.delete(sandbox.id)
```

--------------------------------

### Quick Start: Create and Start a Tunnel

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-tunnel/README.md

Create and start a tunnel using the prime_tunnel library. The local service on the specified port will be accessible via the tunnel URL.

```python
from prime_tunnel import Tunnel

# Create and start a tunnel
async with Tunnel(local_port=8765) as tunnel:
    print(f"Tunnel URL: {tunnel.url}")
    # Your local service on port 8765 is now accessible at tunnel.url
```

--------------------------------

### Install prime-tunnel with uv

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-tunnel/README.md

Install the prime-tunnel package using uv.

```bash
uv pip install prime-tunnel
```

--------------------------------

### Quick Start: Create, Push, and Finalize Evaluation

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-evals/README.md

Initialize the EvalsClient, create an evaluation, push samples, and finalize with metrics. Ensure you replace 'your-api-key' with your actual API key.

```python
from prime_evals import APIClient, EvalsClient

# Initialize client
api_client = APIClient(api_key="your-api-key")
client = EvalsClient(api_client)

# Create an evaluation
eval_response = client.create_evaluation(
    name="gsm8k-gpt4o-baseline",
    model_name="gpt-4o-mini",
    dataset="gsm8k",
    framework="verifiers",
    metadata={
        "version": "1.0",
        "num_examples": 10,
        "temperature": 0.7,
    }
)

eval_id = eval_response["evaluation_id"]
print(f"Created evaluation: {eval_id}")

# Push samples
samples = [
    {
        "example_id": 0,
        "reward": 1.0,
        "correct": True,
        "answer": "18",
        "prompt": [{"role": "user", "content": "What is 9+9?"}],
        "completion": [{"role": "assistant", "content": "The answer is 18."}]
    }
]

client.push_samples(eval_id, samples)

# Finalize with metrics
metrics = {
    "avg_reward": 0.87,
    "avg_correctness": 0.82,
    "success_rate": 0.87,
}

client.finalize_evaluation(eval_id, metrics=metrics)
print("Evaluation finalized!")
```

--------------------------------

### Install Prime MCP Server

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-mcp-server/README.md

Install the prime-mcp-server package using pip or uv.

```bash
pip install prime-mcp-server
```

```bash
uv pip install prime-mcp-server
```

--------------------------------

### Install Prime Sandboxes SDK

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Installs only the lightweight Prime Sandboxes SDK.

```bash
uv pip install prime-sandboxes
```

--------------------------------

### Async Background Job Execution (Python)

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

This asynchronous example shows how to create a sandbox, start a background job, poll for its completion, and then delete the sandbox. It utilizes asyncio for non-blocking operations.

```python
import asyncio
from prime_sandboxes import AsyncSandboxClient, CreateSandboxRequest

async def run_training():
    async with AsyncSandboxClient() as client:
        sandbox = await client.create(CreateSandboxRequest(
            name="async-training",
            docker_image="python:3.11-slim",
            timeout_minutes=720,
        ))
        await client.wait_for_creation(sandbox.id)

        # Start background job
        job = await client.start_background_job(
            sandbox.id,
            "python train.py"
        )

        # Poll until done
        while True:
            status = await client.get_background_job(sandbox.id, job)
            if status.completed:
                print(status.stdout)
                break
            await asyncio.sleep(30)

        await client.delete(sandbox.id)

asyncio.run(run_training())
```

--------------------------------

### Load and Use Installed Environment in Python

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Loads an installed environment using `verifiers.load_environment` and prints its representation. Ensure the environment is installed before running.

```python
from verifiers import load_environment
env = load_environment("gsm8k")
print(env)
```

--------------------------------

### Set Up Prime CLI Workspace

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Command to synchronize and install all packages in editable mode for development.

```bash
# Set up workspace (installs all packages in editable mode)
uv sync
```

--------------------------------

### Create Sandbox with Environment Variables and Secrets

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Example of creating a sandbox and configuring it with environment variables and secrets. Secrets are masked in output and details.

```python
# Create sandbox with environment variables and secrets
request = CreateSandboxRequest(
    name="my-sandbox",
    docker_image="python:3.11-slim",
    environment_vars={
        "DEBUG": "true",
        "LOG_LEVEL": "info"
    },
    secrets={
        "API_KEY": "sk-secret-key-here",
        "DATABASE_PASSWORD": "super-secret-password"
    }
)

sandbox = sandbox_client.create(request)
```

--------------------------------

### Complete Example: Full Evaluation Lifecycle

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-evals/README.md

Demonstrates the full lifecycle of an evaluation, including creation with extensive metadata, batch sample pushing, finalization with computed metrics, and retrieving evaluation details and samples. Replace 'your-api-key' with your actual API key.

```python
from prime_evals import APIClient, EvalsClient

# Initialize
api_client = APIClient(api_key="your-api-key")
client = EvalsClient(api_client)

# Create evaluation with full metadata
eval_response = client.create_evaluation(
    name="gsm8k-experiment-1",
    model_name="gpt-4o-mini",
    dataset="gsm8k",
    framework="verifiers",
    task_type="math",
    description="Baseline evaluation on GSM8K dataset",
    tags=["baseline", "math", "gsm8k"],
    metadata={
        "version": "1.0",
        "timestamp": "2025-10-09T12:00:00Z",
        "num_examples": 100,
        "temperature": 0.7,
        "max_tokens": 2048,
    }
)

eval_id = eval_response["evaluation_id"]

# Push samples in batches
samples_batch = [
    {
        "example_id": i,
        "task": "gsm8k",
        "reward": 1.0 if i % 2 == 0 else 0.5,
        "correct": i % 2 == 0,
        "format_reward": 1.0,
        "correctness": 1.0 if i % 2 == 0 else 0.0,
        "answer": str(i * 2),
        "prompt": [
            {"role": "system", "content": "Solve the math problem."},
            {"role": "user", "content": f"What is {i} + {i}?"}
        ],
        "completion": [
            {"role": "assistant", "content": f"The answer is {i * 2}."}
        ],
        "info": {"batch": 1}
    }
    for i in range(10)
]

client.push_samples(eval_id, samples_batch)

# Finalize with computed metrics
final_metrics = {
    "avg_reward": 0.75,
    "avg_format_reward": 1.0,
    "avg_correctness": 0.50,
    "success_rate": 0.75,
    "total_samples": len(samples_batch),
}

client.finalize_evaluation(eval_id, metrics=final_metrics)

# Retrieve evaluation details
eval_details = client.get_evaluation(eval_id)
print(f"Evaluation Status: {eval_details.get('status')}")

# List all evaluations
evaluations = client.list_evaluations(limit=10)
for eval in evaluations.get("evaluations", []):
    print(f"{eval['name']}: {eval.get('total_samples', 0)} samples")

# Get samples
samples_response = client.get_samples(eval_id, page=1, limit=100)
print(f"Retrieved {len(samples_response.get('samples', []))} samples")
```

--------------------------------

### Create and Manage Sandboxes

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Demonstrates creating, waiting for, executing commands in, uploading/downloading files to, managing background jobs, and deleting sandboxes. Requires `prime-sandboxes` to be installed.

```python
from prime_sandboxes import APIClient, SandboxClient, CreateSandboxRequest, APIError

client  = APIClient()                     # reads PRIME_API_KEY or ~/.prime/config.json
sandbox = SandboxClient(client)

# Create a container sandbox with env vars and secrets
req = CreateSandboxRequest(
    name="ml-runner",
    docker_image="python:3.11-slim",
    start_command="tail -f /dev/null",
    cpu_cores=4,
    memory_gb=8,
    timeout_minutes=240,
    environment_vars={"DATASET": "gsm8k", "EPOCHS": "50"},
    secrets={"HF_TOKEN": "hf_secret_value"},        # never logged
    labels=["experiment-42"],
)
sb = sandbox.create(req)
print(f"Created {sb.id}  status={sb.status}")
```

```python
# Wait until RUNNING (polls every ~2 s, up to max_attempts×2 s)
sandbox.wait_for_creation(sb.id, max_attempts=90)
```

```python
# Execute commands synchronously
result = sandbox.execute_command(sb.id, "python --version")
print(result.stdout, result.exit_code)
```

```python
result = sandbox.execute_command(sb.id, "python -c 'import json; print(json.dumps({\"ok\": True}))'")
print(result.stdout)   # {"ok": true}
```

```python
# Upload a local script and run it
sandbox.upload_file(sb.id, file_path="/app/train.py", local_file_path="./train.py")
result = sandbox.execute_command(sb.id, "python /app/train.py --epochs 10")
print(result.stdout[-2000:])   # tail of output
```

```python
# Download results
sandbox.download_file(sb.id, file_path="/app/metrics.json", local_file_path="./metrics.json")
```

```python
# Long-running background job
job = sandbox.start_background_job(sb.id, "python /app/train.py --epochs 100")
import time
while True:
    status = sandbox.get_background_job(sb.id, job)
    if status.completed:
        print("exit_code:", status.exit_code)
        print(status.stdout[-500:])
        break
    print(f"  running... job_id={job.job_id}")
    time.sleep(30)
```

```python
# Logs
print(sandbox.get_logs(sb.id)[-1000:])
```

```python
# List with label filter
lst = sandbox.list(status="RUNNING", labels=["experiment-42"])
for s in lst.sandboxes:
    print(s.name, s.status)
```

```python
# Cleanup
sandbox.delete(sb.id)
```

--------------------------------

### Manage Environments

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Browses verified environments, views details, inspects source, and installs them locally. Also includes commands to initialize and push custom environments.

```bash
# Browse available environments
prime env list

# View environment details
prime env info <environment-name>

# Inspect environment source without downloading the archive
prime env inspect <environment-name>

# Install an environment locally
prime env install <environment-name>

# Create and push your own environment
prime env init my-environment
prime env push my-environment
```

--------------------------------

### Install Prime CLI Globally

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Command to install the Prime CLI globally in editable mode, making it directly usable.

```bash
# Install CLI globally in editable mode
uv tool install -e packages/prime
```

--------------------------------

### Install prime-tunnel with pip

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-tunnel/README.md

Install the prime-tunnel package using pip.

```bash
pip install prime-tunnel
```

--------------------------------

### Prime Python SDK: Sandbox Management

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Example of using the Prime Python SDK to initialize a client, create, wait for, execute commands in, and delete a sandbox.

```python
from prime_sandboxes import APIClient, SandboxClient, CreateSandboxRequest

# Initialize client
client = APIClient(api_key="your-api-key")
sandbox_client = SandboxClient(client)

# Create a sandbox
sandbox = sandbox_client.create(CreateSandboxRequest(
    name="my-sandbox",
    docker_image="python:3.11-slim",
    cpu_cores=2,
    memory_gb=4,
))

# Wait for creation
sandbox_client.wait_for_creation(sandbox.id)

# Execute commands
result = sandbox_client.execute_command(sandbox.id, "python --version")
print(result.stdout)

# Clean up
sandbox_client.delete(sandbox.id)
```

--------------------------------

### Create and Manage Disks

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Shows how to create, list, get details, rename, and delete persistent network-attached storage disks. Ensure the `DisksClient` is initialized with an `APIClient`.

```python
from prime_cli.core import APIClient
from prime_cli.api.disks import DisksClient

client = APIClient()
disks = DisksClient(client)

# Create
disk = disks.create({
    "size": 500,          # GB
    "name": "training-data",
    "cloudId": "some-cloud-id",
})
print(f"Disk {disk.id} – status: {disk.status}  ${disk.price_hr}/hr")
```

```python
disk_list = disks.list()
for d in disk_list.data:
    print(d.id, d.name, d.size, "GB", d.status, d.pods)
```

```python
d = disks.get(disk.id)
```

```python
disks.update(disk.id, name="renamed-disk")
```

```python
resp = disks.delete(disk.id)
print(resp.status)   # "ok"
```

--------------------------------

### Run the MCP Server

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-mcp-server/README.md

Start the Prime MCP server using the Python module. The server communicates over stdio.

```python
python -m prime_mcp.mcp
```

--------------------------------

### CLI: Start a Tunnel

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-tunnel/README.md

Start a tunnel using the Prime CLI, exposing a local service on the specified port.

```bash
prime tunnel start --port 8765
```

--------------------------------

### Environments Hub CLI

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Commands for browsing, inspecting, installing, publishing, and managing environments in the Environments Hub.

```APIDOC
## Environments Hub CLI

### Browse environments
```bash
# Browse public environments with filtering
prime env list
prime env list --search "math" --sort stars --tag reasoning
prime env list --mine --show-actions
```

### Inspect environments
```bash
# Inspect without downloading
prime env info openai/gsm8k
prime env inspect openai/gsm8k
prime env inspect openai/gsm8k@0.2.1 env.py     # view specific file
```

### Install environments
```bash
# Install from hub (uses uv by default)
prime env install openai/gsm8k
prime env install openai/gsm8k@0.2.1 --with pip
prime env install env1 env2 env3                  # batch install
```

### Use in Python
```python
# Use in Python after install
from verifiers import load_environment
env = load_environment("gsm8k")
print(env)
```

### Publish environments
```bash
# Publish your own environment
prime env init my-reward-env
prime env push my-reward-env
prime env push my-reward-env --visibility PUBLIC --auto-bump
```

### Manage versions
```bash
# Manage versions
prime env version list openai/gsm8k
prime env version delete openai/gsm8k <content-hash> --force
```

### Manage CI actions
```bash
# Manage CI actions (integration tests)
prime env action list openai/gsm8k
prime env action logs openai/gsm8k <job-id> --follow
prime env action retry openai/gsm8k
```

### Manage environment secrets and variables
```bash
# Manage environment secrets and variables
prime env secret list openai/gsm8k
prime env secret create openai/gsm8k --name HF_TOKEN --value hf_xxx
prime env var create openai/gsm8k --name MAX_RETRIES --value 3
```
```

--------------------------------

### Prime Python SDK: Async Sandbox Management

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Example of using the asynchronous Prime Python SDK to create, execute commands in, and delete a sandbox within an async context.

```python
import asyncio
from prime_sandboxes import AsyncSandboxClient, CreateSandboxRequest

async def main():
    async with AsyncSandboxClient(api_key="your-api-key") as client:
        sandbox = await client.create(CreateSandboxRequest(
            name="async-sandbox",
            docker_image="python:3.11-slim",
        ))

        await client.wait_for_creation(sandbox.id)
        result = await client.execute_command(sandbox.id, "echo 'Hello'")
        print(result.stdout)

        await client.delete(sandbox.id)

asyncio.run(main())
```

--------------------------------

### List and Get Evaluations

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Commands to list all evaluations and retrieve details for a specific evaluation.

```bash
# List all evaluations
prime eval list
```

```bash
# Get evaluation details
prime eval get <eval-id>
```

```bash
# View evaluation samples
prime eval samples <eval-id>
```

--------------------------------

### Get Samples

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-evals/README.md

Retrieves samples for a specific evaluation, with pagination.

```APIDOC
## get_samples

### Description
Retrieves samples for a specific evaluation, with pagination.

### Method
`client.get_samples(eval_id: str, page: int = 1, limit: int = 100)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eval_id** (str) - Required - The ID of the evaluation to retrieve samples from.
- **page** (int) - Optional - The page number for pagination (defaults to 1).
- **limit** (int) - Optional - The number of samples to return per page (defaults to 100).

### Request Example
```python
samples_response = client.get_samples("eval-12345abcde", page=1, limit=100)
print(f"Retrieved {len(samples_response.get('samples', []))} samples")
```

### Response
#### Success Response (200)
- **samples** (List[Dict[str, Any]]) - A list of sample objects.

#### Response Example
```json
{
  "samples": [
    {
      "example_id": 0,
      "reward": 1.0,
      "correct": True,
      "answer": "18",
      "prompt": [{"role": "user", "content": "What is 9+9?"}],
      "completion": [{"role": "assistant", "content": "The answer is 18."}]
    }
  ]
}
```
```

--------------------------------

### Async Usage: Asynchronous Sandbox Operations

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Demonstrates how to use the AsyncSandboxClient for asynchronous sandbox operations. This example uses an async context manager for the client and awaits operations.

```python
import asyncio
from prime_sandboxes import AsyncSandboxClient, CreateSandboxRequest

async def main():
    async with AsyncSandboxClient(api_key="your-api-key") as client:
        # Create sandbox
        sandbox = await client.create(CreateSandboxRequest(
            name="async-sandbox",
            docker_image="python:3.11-slim",
        ))

        # Wait and execute
        await client.wait_for_creation(sandbox.id)
        result = await client.execute_command(sandbox.id, "echo 'Hello from async!'")
        print(result.stdout)

        # Clean up
        await client.delete(sandbox.id)

asyncio.run(main())
```

--------------------------------

### Get Deployable Base Models for Adapters

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Retrieve a list of base models that are available for deploying LoRA adapters using `DeploymentsClient.get_deployable_models`.

```python
from prime_cli.core import APIClient
from prime_cli.api.deployments import DeploymentsClient

client = APIClient()
dep    = DeploymentsClient(client)

# Get deployable base models
models = dep.get_deployable_models()
print("deployable base models:", models)
```

--------------------------------

### Prime Intellect API Client Authentication and Usage

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Demonstrates how to authenticate with the Prime Intellect API using an API key, environment variables, or stored credentials. Shows basic GET requests and error handling for common API errors like unauthorized access or payment issues. The async version is also shown with context manager usage.

```python
import os
from prime_cli.core import APIClient, APIError, UnauthorizedError, PaymentRequiredError

# Option 1 – explicit key
client = APIClient(api_key="sk-your-key-here")

# Option 2 – environment variable (no argument needed)
os.environ["PRIME_API_KEY"] = "sk-your-key-here"
client = APIClient()

# Option 3 – key already stored by `prime login`; auto-loaded from ~/.prime/config.json
client = APIClient()

# Low-level request helper (auto-prepends /api/v1)
try:
    data = client.get("/pods", params={"offset": 0, "limit": 5})
    print(data)
except UnauthorizedError:
    print("Invalid or expired API key")
except PaymentRequiredError:
    print("Billing issue – check https://app.primeintellect.ai/dashboard/billing")
except APIError as e:
    print(f"Other API error: {e}")
finally:
    client.client.close()

# Async version (context-manager recommended)
from prime_cli.core import AsyncAPIClient
import asyncio

async def example():
    async with AsyncAPIClient(api_key="sk-your-key") as aclient:
        data = await aclient.get("/pods", params={"limit": 3})
        print(data)

asyncio.run(example())
```

--------------------------------

### Long-Running Tasks: Start Background Job

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Example of starting a long-running job within a sandbox that continues execution after the API call returns. Use `get_background_job` to poll for its status.

```python
from prime_sandboxes import SandboxClient, CreateSandboxRequest

sandbox_client = SandboxClient()

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

# Start a long-running job in the background
job = sandbox_client.start_background_job(
    sandbox.id,
    "python train.py --epochs 100"
)
print(f"Job started: {job.job_id}")
```

--------------------------------

### Manage Hosted Training Models

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Lists available Hosted Training models, their capacity, and pricing. Also initializes and launches a training configuration.

```bash
# See available Hosted Training models, capacity, and pricing
prime train models

# Generate and launch a Hosted Training config
prime train init
prime train rl.toml
```

--------------------------------

### Create and Manage Pods

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Demonstrates creating, listing, polling, retrieving details, and terminating pods. Ensure necessary configurations are set before execution.

```python
pod_config = {
    "cloudId":       cfg.cloud_id,
    "gpuType":       cfg.gpu_type,
    "socket":        cfg.socket,
    "gpuCount":      cfg.gpu_count,
    "diskSize":      100,             # GB
    "image":         "ubuntu:22.04",
    "name":          "my-training-pod",
}
pod = pods.create(pod_config)
print(f"Pod {pod.id} created – status: {pod.status}")
```

```python
pod_list = pods.list(offset=0, limit=50)
for p in pod_list.data:
    print(f"{p.id}  {p.name}  {p.gpu_type}×{p.gpu_count}  {p.status}  ${p.price_hr}/hr")
```

```python
import time
while True:
    statuses = pods.get_status([pod.id])
    s = statuses[0]
    print(f"  status={s.status}  ssh={s.ssh_connection}  progress={s.installation_progress}%")
    if s.status == "RUNNING":
        break
    time.sleep(10)
```

```python
p = pods.get(pod.id)
print(p.ssh_connection, p.jupyter_password)
```

```python
pods.delete(pod.id)
print("Pod terminated")
```

```python
history = pods.history(limit=20)
for h in history.data:
    print(h.id, h.gpu_name, h.total_billed_price)
```

--------------------------------

### Set up Lab Workspace

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Initializes a local workspace for Prime Lab, including starter configurations.

```bash
prime lab setup
```

--------------------------------

### Run Basic Sandbox Demo

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Executes the basic demonstration script for the sandbox functionality. Ensure you have cloned the repository and run 'uv sync'.

```bash
uv run python examples/sandbox_demo.py
```

--------------------------------

### Manage Hosted Training Runs

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Lists available models and pricing, initializes a training configuration interactively, launches training from a config file, or manages existing runs (list, logs, metrics, checkpoints, stop).

```bash
# Hosted Training
prime train models             # available models + pricing
prime train init               # generate rl.toml config interactively
prime train rl.toml            # launch from config file
prime train list
prime train logs <run-id> -f
prime train metrics <run-id>
prime train checkpoints <run-id>
prime train stop <run-id>
```

--------------------------------

### Publish Your Own Environment

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Initializes a new environment package and pushes it to the hub. You can control visibility and automatically bump versions.

```bash
prime env init my-reward-env
prime env push my-reward-env
prime env push my-reward-env --visibility PUBLIC --auto-bump
```

--------------------------------

### Create GPU Pod

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Launches a GPU compute pod with a specified configuration.

```bash
prime pods create --gpu A100 --count 1
```

--------------------------------

### Get Evaluation

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-evals/README.md

Retrieves the details of a specific evaluation.

```APIDOC
## get_evaluation

### Description
Retrieves the details of a specific evaluation.

### Method
`client.get_evaluation(eval_id: str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **eval_id** (str) - Required - The ID of the evaluation to retrieve.

### Request Example
```python
eval_details = client.get_evaluation("eval-12345abcde")
print(f"Evaluation Status: {eval_details.get('status')}")
```

### Response
#### Success Response (200)
- **status** (str) - The current status of the evaluation.
- Other evaluation details may be included.

#### Response Example
```json
{
  "evaluation_id": "eval-12345abcde",
  "name": "gsm8k-gpt4o-baseline",
  "status": "completed",
  "total_samples": 10
}
```
```

--------------------------------

### Get Evaluation Samples

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Retrieve samples for a given evaluation ID.

```bash
prime eval samples <eval-id>
```

--------------------------------

### Generate Hosted Training Config

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Initializes a configuration file for a Hosted Training run.

```bash
prime train init
```

```bash
prime train rl.toml
```

--------------------------------

### Listing and Getting Evals

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Commands to list all available evaluations or retrieve details for a specific evaluation.

```APIDOC
## Evals Management

### Description
Commands for managing evaluations.

### Usage

1. **List all evals**:
   ```bash
   prime eval list
   ```

2. **Get specific eval**:
   ```bash
   prime eval get <eval_id>
   ```

3. **View eval samples**:
   ```bash
   prime eval samples <eval_id>
   ```
```

--------------------------------

### CLI: Get Tunnel Status

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-tunnel/README.md

Retrieve the status of a specific tunnel using its ID with the Prime CLI.

```bash
prime tunnel status <tunnel_id>
```

--------------------------------

### Query Available GPU Resources with AvailabilityClient

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Shows how to use the AvailabilityClient to query for available GPU resources. Demonstrates fetching all available GPUs, filtering by type and region, and retrieving lists of available GPU types and disk configurations. Requires an initialized APIClient.

```python
from prime_cli.core import APIClient
from prime_cli.api.availability import AvailabilityClient

client = APIClient()
avail = AvailabilityClient(client)

# All available GPUs
gpu_map = avail.get()
for gpu_type, configs in gpu_map.items():
    for cfg in configs:
        status = cfg.stock_status          # "in_stock" | "low_stock" | "out_of_stock"
        price  = cfg.prices.price          # USD/hr (community or on-demand)
        print(f"{gpu_type}  {cfg.gpu_count}x  ${price:.3f}/hr  {cfg.data_center}  [{status}]")

# Filter by GPU type and region
h100_configs = avail.get(gpu_type="H100_80GB", regions=["US"])
for cfg in h100_configs.get("H100_80GB", []):
    print(cfg.cloud_id, cfg.gpu_count, cfg.prices.community_price)

# Available GPU types list
types = avail.get_available_gpu_types()
# -> ["H100_80GB", "A100_80GB", "A100_40GB", "H200_141GB", ...]
print(types)

# Disk availability
disks = avail.get_disks(regions=["US"])
for d in disks:
    print(d.cloud_id, d.spec.price_per_unit, d.spec.max_count)
```

--------------------------------

### Environment Hub Operations

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Commands for interacting with the Prime Intellect environments hub, including viewing details, inspecting, installing, and managing custom environments.

```bash
prime env info <environment-name>
```

```bash
prime env inspect <environment-name>
```

```bash
prime env install <environment-name>
```

```bash
prime env init my-environment
```

```bash
prime env push my-environment
```

--------------------------------

### List Available Base Models and Pricing

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Use `RLClient` to list available base models for Hosted Training, including their capacity status and pricing per megatok. Requires `APIClient` initialization.

```python
from prime_cli.core import APIClient
from prime_cli.api.rl import RLClient

base   = APIClient()
rl     = RLClient(base)

# 1. List available base models and pricing
models = rl.list_models()
for m in models:
    tp = m.training_price_per_mtok or 0
    print(f"{m.name}  capacity={'FULL' if m.at_capacity else 'OK'}  ${tp:.2f}/Mtok  {m.promo_label or ''}")
```

--------------------------------

### Get Specific Eval Details

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Fetches detailed information about a specific evaluation using its unique ID. Replace '<eval_id>' with the actual evaluation ID.

```bash
prime eval get <eval_id>
```

--------------------------------

### Create Sandbox

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Create a new sandbox environment. Supports specifying Python version or a custom VM image with GPU configurations.

```bash
prime sandbox create python:3.11
prime sandbox create user/vm-image:latest --vm --gpu-count 1 --gpu-type H100_80GB
```

--------------------------------

### List Sandboxes

Source: https://context7.com/primeintellect-ai/prime/llms.txt

List all available sandbox environments.

```bash
prime sandbox list
```

--------------------------------

### View Hosted Training Models

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Displays available Hosted Training models, their current capacity, and pricing information.

```bash
prime train models
```

--------------------------------

### Browse Environments

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Lists available environments on the Prime Intellect hub.

```bash
prime env list
```

--------------------------------

### Programmatic Infrastructure Automation

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Use PodsClient, DisksClient, and AvailabilityClient for programmatic discovery and provisioning of GPU pods, attaching disks, and SSH access.

```python
from prime import PodsClient, DisksClient, AvailabilityClient

# Example usage (conceptual)
pods_client = PodsClient()
disks_client = DisksClient()
availability_client = AvailabilityClient()

# Provision a GPU pod
pod = pods_client.create_pod(gpu_type="H100_80GB", count=1)

# Attach a persistent disk
disk = disks_client.create_disk(size_gb=100)
disks_client.attach_disk(pod_id=pod.id, disk_id=disk.id)

# SSH into an instance
# availability_client.ssh_into_instance(instance_id=pod.instance_id)
```

--------------------------------

### File Operations: Upload and Download

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Demonstrates how to upload a local file to a sandbox and download a file from a sandbox. Ensure the sandbox is running and paths are correct.

```python
# Upload a file
sandbox_client.upload_file(
    sandbox_id=sandbox.id,
    file_path="/app/script.py",
    local_file_path="./local_script.py"
)

# Download a file
sandbox_client.download_file(
    sandbox_id=sandbox.id,
    file_path="/app/output.txt",
    local_file_path="./output.txt"
)
```

--------------------------------

### Bulk Operations: Create and Delete Sandboxes

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Shows how to create multiple sandboxes in a loop, wait for all of them to be ready, and then delete them either by their IDs or by labels.

```python
# Create multiple sandboxes
sandbox_ids = []
for i in range(5):
    sandbox = sandbox_client.create(CreateSandboxRequest(
        name=f"sandbox-{i}",
        docker_image="python:3.11-slim",
    ))
    sandbox_ids.append(sandbox.id)

# Wait for all to be ready
statuses = sandbox_client.bulk_wait_for_creation(sandbox_ids)

# Delete by IDs or labels
sandbox_client.bulk_delete(sandbox_ids=sandbox_ids)
# OR by labels
sandbox_client.bulk_delete(labels=["experiment-1"])
```

--------------------------------

### Machine Learning Training Pod Deployment

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Commands to create a pod with specified GPU resources for machine learning training and then SSH into it.

```bash
# Deploy a pod with 8x H100 GPUs
prime pods create --gpu H100 --count 8 --name ml-training

# SSH and start training
prime pods ssh <pod-id>
```

--------------------------------

### Get RL Run Usage and Wallet Balance

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Retrieves token usage details for a specific RL run, including training and inference costs. Also fetches current wallet balance and recent billing entries.

```python
from prime_cli.core import APIClient
from prime_cli.api.billing import BillingClient
from prime_cli.api.wallet import WalletClient

client  = APIClient()
billing = BillingClient(client)
wallet  = WalletClient(client)

# Token usage for a specific RL run
usage = billing.get_run_usage("run-id-here")
print(f"Run: {usage.run_name}  model={usage.base_model}  status={usage.status}")
print(f"  training tokens: {usage.training.tokens:,}  cost: ${usage.training.cost_usd:.4f}")
print(f"  inference tokens: {usage.inference.tokens:,}  cost: ${usage.inference.cost_usd:.4f}")
print(f"  total cost: ${usage.total_cost_usd:.4f}")

# Current wallet balance and recent billing entries
w = wallet.get(limit=10)
print(f"Balance: ${w.balance_usd:.2f}  {w.currency}")
for entry in w.recent_billings:
    print(f"  {entry.created_at.date()}  {entry.resource_type:20s}  ${entry.amount_usd:.4f}")
```

--------------------------------

### Create VM Sandbox with GPUs via CLI

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Command to create a virtual machine sandbox with specified GPU count and type. Use this for GPU-accelerated workloads.

```bash
prime sandbox create user-1/vm-image:latest --vm --gpu-count 1 --gpu-type H100_80GB
```

--------------------------------

### Create a Hosted Training Run

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Initiate a Hosted Training run using `RLClient.create_run`. Specify model, environments, training parameters, and Weights & Biases configuration. Requires an initialized `APIClient`.

```python
from prime_cli.core import APIClient
from prime_cli.api.rl import RLClient

base   = APIClient()
rl     = RLClient(base)

# 2. Create a run
run = rl.create_run(
    model_name="Qwen/Qwen2.5-7B-Instruct",
    environments=[{"name": "openai/gsm8k", "weight": 1.0}],
    rollouts_per_example=8,
    max_steps=500,
    max_tokens=1024,
    batch_size=64,
    learning_rate=1e-5,
    lora_alpha=64,
    name="gsm8k-qwen-v1",
    wandb_entity="my-org",
    wandb_project="prime-rl",
    secrets={"HF_TOKEN": "hf_secret"},
)
print(f"Run {run.id} created – status: {run.status}")
```

--------------------------------

### Manage Hosted Training Runs

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Commands for listing, viewing logs, and inspecting metrics of Hosted Training runs.

```bash
prime train list
```

```bash
prime train logs <run-id> -f
```

```bash
prime train metrics <run-id>
```

```bash
prime train checkpoints <run-id>
```

--------------------------------

### Automate Hosted Training Lifecycle

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Use RLClient and DeploymentsClient to automate the complete Hosted Training lifecycle, from dataset environment selection to LoRA adapter deployment.

```python
from prime import RLClient, DeploymentsClient

rl_client = RLClient()
deployments_client = DeploymentsClient()

# Select a dataset environment
dataset_env = rl_client.select_dataset_environment(dataset_id="my_dataset", model_id="base_model")

# Train a LoRA adapter
training_job = rl_client.train_lora_adapter(dataset_env_id=dataset_env.id, output_dir="/training/output")

# Deploy the adapter
deployment = deployments_client.deploy_lora_adapter(training_job_id=training_job.id, model_name="my_lora_model")
```

--------------------------------

### Prime CLI - Compute, Training, and Evaluation

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Commands for managing GPU availability, pods, and hosted training jobs.

```APIDOC
### Compute, training, and evaluation

```bash
# GPU availability
prime availability list
prime availability list --gpu-type H100_80GB --regions US
prime availability gpu-types

# Pods
prime pods list
prime pods create --id <cloud-id> --name my-pod
prime pods status <pod-id>
prime pods ssh <pod-id>
prime pods terminate <pod-id>

# Hosted Training
prime train models             # available models + pricing
prime train init               # generate rl.toml config interactively
prime train rl.toml            # launch from config file
prime train list
prime train logs <run-id> -f
prime train metrics <run-id>
prime train checkpoints <run-id>
prime train stop <run-id>
```
```

--------------------------------

### Create Sandbox Programmatically

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Demonstrates how to programmatically create a sandbox using the Prime API client. This includes setting configurations like name, Docker image, resources, and environment variables.

```python
from prime_core import APIClient
from prime_sandboxes import SandboxClient, CreateSandboxRequest

# Initialize client
client = APIClient()
sandbox_client = SandboxClient(client)

# Create sandbox
request = CreateSandboxRequest(
    name="my-sandbox",
    docker_image="python:3.11-slim",
    start_command="python app.py",
    cpu_cores=2,
    memory_gb=4,
    disk_size_gb=20,
    gpu_count=0,
    gpu_type=None,
    timeout_minutes=60,
    environment_vars={"ENV": "production"},
    secrets={"API_KEY": "your-secret-key"},
    team_id=None  # Use None for personal account
)

sandbox = sandbox_client.create(request)
print(f"Created sandbox: {sandbox.id}")
```

--------------------------------

### Manage Pods

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Lists existing pods and creates new pods, with options to specify a GPU configuration or a custom name.

```bash
# List your pods
prime pods list

# Create a pod
prime pods create
prime pods create --id <ID>     # With specific GPU config
prime pods create --name my-pod # With custom name
```

--------------------------------

### Manage Hosted Training Runs

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Lists, views logs, metrics, and checkpoints for Hosted Training runs. Use the -f flag with logs to follow output.

```bash
# Inspect and manage Hosted Training runs
prime train list
prime train logs <run-id> -f
prime train metrics <run-id>
prime train checkpoints <run-id>
```

--------------------------------

### Create CPU-only VM Sandbox via CLI

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Command to create a virtual machine sandbox using only CPU resources. Suitable for general-purpose VM tasks.

```bash
prime sandbox create user-1/vm-image:latest --vm
```

--------------------------------

### Create Sandbox Environment

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Initializes an isolated sandbox environment. Specify the runtime, e.g., python:3.11.

```bash
prime sandbox create python:3.11
```

--------------------------------

### Advanced Sandbox Creation

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Commands for creating sandboxes with specific configurations, including VM sandboxes with GPUs or CPU-only VMs.

```bash
prime sandbox create user-1/vm-image:latest --vm --gpu-count 1 --gpu-type H100_80GB
```

```bash
prime sandbox create user-1/vm-image:latest --vm
```

--------------------------------

### Manage GPU Resources

Source: https://github.com/primeintellect-ai/prime/blob/main/README.md

Lists all available GPUs and allows filtering by GPU type. Also shows available GPU types.

```bash
# List all available GPUs
prime availability list

# Filter by GPU type
prime availability list --gpu-type H100_80GB

# Show available GPU types
prime availability gpu-types
```

--------------------------------

### Initialize PodsClient for Pod Management

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Demonstrates the initialization of the PodsClient, which is used for managing GPU pods. It requires an initialized base APIClient. This snippet is a precursor to pod creation and management operations.

```python
from prime_cli.core import APIClient
from prime_cli.api.pods import PodsClient
from prime_cli.api.availability import AvailabilityClient

base = APIClient()
pods = PodsClient(base)
avail = AvailabilityClient(base)

# 1. Find an available H100 config
gpu_map = avail.get(gpu_type="H100_80GB")
cfg = gpu_map["H100_80GB"][0]  # first available slot

```

--------------------------------

### Upload and Download Files in Sandbox

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Upload a local file to a remote path in the sandbox or download a remote file to the local system.

```bash
prime sandbox upload <id> local.py /remote/
prime sandbox download <id> /remote/out.txt ./
```

--------------------------------

### Labels & Filtering: Create with Labels and List Sandboxes

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime-sandboxes/README.md

Illustrates creating a sandbox with specific labels and then listing sandboxes, filtering by status and labels. This is useful for organizing and managing multiple sandboxes.

```python
# Create with labels
sandbox = sandbox_client.create(CreateSandboxRequest(
    name="labeled-sandbox",
    docker_image="python:3.11-slim",
    labels=["experiment", "ml-training"],
))

# List with filters
sandboxes = sandbox_client.list(
    status="RUNNING",
    labels=["experiment"],
    page=1,
    per_page=50,
)

for s in sandboxes.sandboxes:
    print(f"{s.name}: {s.status}")
```

--------------------------------

### Manage Pods

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Lists existing pods, creates a new pod with a specified cloud ID and name, checks status, connects via SSH, or terminates a pod.

```bash
# Pods
prime pods list
prime pods create --id <cloud-id> --name my-pod
prime pods status <pod-id>
prime pods ssh <pod-id>
prime pods terminate <pod-id>
```

--------------------------------

### List GPU Availability

Source: https://github.com/primeintellect-ai/prime/blob/main/packages/prime/README.md

Shows available GPU resources.

```bash
prime availability list
```

--------------------------------

### Browse Public Environments with Filtering

Source: https://context7.com/primeintellect-ai/prime/llms.txt

Lists public environments from the hub, with options to search by keyword, sort by stars, and filter by tags. Use `--mine` to list your own environments.

```bash
prime env list
prime env list --search "math" --sort stars --tag reasoning
prime env list --mine --show-actions
```

--------------------------------

### Run Async Sandbox Demo

Source: https://github.com/primeintellect-ai/prime/blob/main/examples/README.md

Executes the asynchronous demonstration script for the sandbox functionality. This is useful for testing non-blocking operations.

```bash
uv run python examples/sandbox_async_demo.py
```