---
name: provider-adapters
description: >
  Operating each GPU provider: exact CLI/API commands for RunPod, Vast.ai,
  Modal, Lambda, and Prime — search, provision, wait-for-ready, SSH, destroy —
  plus gotchas per provider. Use whenever gpu_provision's template fails, or
  when you need live pricing, instance details, or a manual provisioning flow.
---

# Provider Adapters

Deep playbooks live in `docs/providers/<provider>.md` inside this package —
read the relevant one for full command sets. This skill is the cheat sheet and
the fallback path when the extension's command templates fail. Rule: if a
template command fails, do the provider flow below by hand (API/CLI), then
`gpu_register` the result.

## Vast.ai (vastai CLI) — cheapest, most hands-on

```bash
# live search — ALWAYS search before provisioning (prices are a marketplace)
vastai search offers 'gpu_name=RTX 5090' --order 'dph_total asc' --limit 10 --raw
# pick the bundle id from the JSON (cheapest dph_total with enough disk; note
# dph_total includes storage, dph is GPU-only)
vastai create instance <bundle_id> --disk 50 --image nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 --ssh --direct
vastai show instance <id>            # wait for status running; get ssh host/port
vastai destroy instance <id>
```

Gotchas: storage billed separately and per hour; interruptible offers are
cheaper but can be reclaimed (fine for retryable queues, dangerous for
one-shot); geolocation matters for egress; `--direct` gives a public port.

## RunPod (runpodctl) — managed, predictable

```bash
runpodctl get templates --output json          # find a comfyui template id
# API flow (richer than the CLI — POST with your API key):
curl -s -X POST https://api.runpod.io/v2/pods \
  -H "Authorization: Bearer $RUNPOD_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"vf-h3","gpuTypeId":"NVIDIA GeForce RTX 5090","templateId":"<id>","cloudType":"COMMUNITY","containerDiskInGb":20,"volumeInGb":50}'
curl -s https://api.runpod.io/v2/pods -H "Authorization: Bearer $RUNPOD_API_KEY"   # poll status → RUNNING
runpodctl remove pod <id>
```

Gotchas: community cloud is ~2x cheaper than secure but has no SLA; template
images (comfyui) save the whole install step; GPU type ids are exact strings
(`NVIDIA GeForce RTX 4090`, `NVIDIA H100 80GB SXM`).

## Modal (modal CLI) — serverless, zero idle cost

```bash
modal profile current        # auth check
modal secret create video-factory  # if the app needs HF tokens etc.
modal deploy                 # from the app dir — deploys the container
```

No machines, no destroy, no SSH. A deployment is an app URL; billing runs only
while a container executes. GPU choice is code
(`@app.function(gpu="H100")`). Gotcha: cold starts; containers scale to zero —
great for sparse batches, wrong for long-running queues (restart cost per
scale-up, see gpu-ops math).

## Lambda (API) — premium, no egress fees

```bash
curl -s https://api.lambdalabs.com/v1/instance-types -H "Authorization: Bearer $LAMBDA_API_KEY"   # → instance_type_name list (e.g. gpu_1x_h100_sxm)
curl -s -X POST https://api.lambdalabs.com/v1/instances -H "Authorization: Bearer $LAMBDA_API_KEY" -H "Content-Type: application/json" \
  -d '{"instance_type_name":"gpu_1x_h100_sxm","region_name":"us-east-1","ssh_key_names":["<key>"]}'
curl -s https://api.lambdalabs.com/v1/instances -H "Authorization: Bearer $LAMBDA_API_KEY"        # wait for active
curl -s -X DELETE https://api.lambdalabs.com/v1/instances/<id> -H "Authorization: Bearer $LAMBDA_API_KEY"
```

Gotcha: single-GPU on-demand starts fast; multi-GPU HGX requires a commitment
(2 weeks+). No CLI — key must be in the environment.

## Prime Intellect (prime CLI) — decentralized marketplace

```bash
prime --help                   # verify current CLI surface — it changes
# Expected surface: rent/search clusters, spot bids, per-cluster pricing
```

Gotchas: pricing is dynamic per cluster (bid or take ask); spot exists for
retryable work. Verify the exact commands against docs.primeintellect.ai at
deploy time and prefer the `docs/providers/prime.md` playbook.

## Salad (REST API) — the aggressive economics lane

No CLI — `SALAD_API_KEY` + `SALAD_ORG` + `SALAD_PROJECT` in the environment.
You deploy Docker **containers**, not pods:

```bash
curl -s https://api.salad.com/api/public/gpu-classes -H "Salad-Api-Key: $SALAD_API_KEY"
curl -s -X POST https://api.salad.com/api/public/organizations/$SALAD_ORG/projects/$SALAD_PROJECT/containers \
  -H "Salad-Api-Key: $SALAD_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"vf-h3","container_groups":[{"name":"vf-h3","container":{"image":"yourorg/h3-worker:latest"},"resources":{"gpu_classes":["rtx_5090"],"gpus":1}}]}'
curl -s https://api.salad.com/api/public/organizations/$SALAD_ORG/projects/$SALAD_PROJECT/containers/$NAME -H "Salad-Api-Key: $SALAD_API_KEY"
curl -s -X DELETE https://api.salad.com/api/public/organizations/$SALAD_ORG/projects/$SALAD_PROJECT/containers/$NAME -H "Salad-Api-Key: $SALAD_API_KEY"
```

Gotchas: bring your own container image (pushed to a registry); batch pricing
on a distributed fleet — availability varies, retryable batches only; ~2x
cheaper than Vast when container startup is fast, otherwise the savings
vanish. Full playbook: `docs/providers/salad.md`.

## After any manual flow

1. Wait for the instance to be reachable (SSH or HTTP).
2. Install runtime + weights (comfyui / model-deployment skills).
3. Health-check with a test generation.
4. `gpu_register` with endpoint + ssh + real cost_hr → READY.
5. Only then `gpu_run`.