# Quickstart: rent a GPU with the API

This page takes you from an API key to a running RTX 4090 you can SSH into, then shuts it down. It uses plain HTTP, so it works the same from `curl`, Python, or an AI agent. Allow about five minutes.

- **API base URL:** `https://api.green-compute.com`
- **Auth:** `Authorization: Bearer <your API key>` on every request except the public ones marked below

## 0. One-time setup (a human does this once)

1. Sign in at [green-compute.com/login](https://www.green-compute.com/login).
2. Add credit on the [Billing](https://www.green-compute.com/billing) page (card or TAO). Starting a rental needs at least **one hour** of its price in your balance.
3. Create an API key under [Settings → API keys](https://www.green-compute.com/settings).

Everything after this step is API-only.

```bash
export GC_KEY="paste-your-api-key"
export GC_API="https://api.green-compute.com"
```

## 1. Check price and availability (public, no key)

```bash
curl -s "$GC_API/platform/pricing"
curl -s https://control.green-compute.com/platform/v1/gpu-pool
```

`/platform/pricing` is the exact rate billing charges. `gpu-pool` shows how many GPUs of each model are free right now. GPU ids are `rtx4090` and `rtx5090`, and any spelling works on input (`"RTX 4090"`, `"rtx-4090"`).

## 2. Describe the machine you want

A *workload* says what to run: the image and the hardware. Put your own SSH **public** key in `metadata.ssh_public_keys` so you can log in with a key you already hold.

```bash
WORKLOAD_ID=$(curl -s -X POST "$GC_API/platform/workloads" \
  -H "Authorization: Bearer $GC_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "my-gpu-box",
    "kind": "pod",
    "image": "pytorch/pytorch:2.7.0-cuda12.8-cudnn9-runtime",
    "requirements": {
      "gpu_count": 1,
      "supported_gpu_models": ["rtx4090"],
      "min_vram_gb_per_gpu": 24,
      "cpu_cores": 8,
      "memory_gb": 32
    },
    "metadata": {
      "ssh_public_keys": ["'"$(cat ~/.ssh/id_ed25519.pub)"'"],
      "volume_size_gb": 50
    }
  }' | python3 -c 'import sys,json; print(json.load(sys.stdin)["workload_id"])')
echo "$WORKLOAD_ID"
```

## 3. Start it

A *deployment* is a running instance of the workload. Billing starts when it reaches `ready`, so time spent pulling the image is free.

```bash
DEPLOYMENT_ID=$(curl -s -X POST "$GC_API/platform/deployments" \
  -H "Authorization: Bearer $GC_KEY" -H "Content-Type: application/json" \
  -d "{\"workload_id\": \"$WORKLOAD_ID\"}" \
  | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d["deployment_id"]); print("rate cents/GPU/hr:", d["hourly_rate_cents"], file=sys.stderr)')
```

`hourly_rate_cents` in the response is the most this deployment can cost per GPU-hour. With a single GPU model it is the exact rate. Once a GPU is assigned, the field updates to that card's rate, which is never higher. There is no deployment fee: `deployment_fee_usd` is always `0`.

## 4. Wait until it is ready

```bash
while true; do
  STATE=$(curl -s "$GC_API/platform/deployments/$DEPLOYMENT_ID" -H "Authorization: Bearer $GC_KEY" \
          | python3 -c 'import sys,json; print(json.load(sys.stdin)["state"])')
  echo "$STATE"
  case "$STATE" in ready) break ;; failed|terminated) exit 1 ;; esac
  sleep 10
done
```

States run `pending → scheduled → pulling → starting → ready`. Usually this takes one to three minutes; the first pull of a large image takes longer.

## 5. Connect

```bash
curl -s "$GC_API/platform/deployments/$DEPLOYMENT_ID/ssh" -H "Authorization: Bearer $GC_KEY"
# {"ssh_host": "...", "ssh_port": 40123, "ssh_username": "root", "ssh_command": "ssh root@... -p 40123", "private_key": "..."}
ssh root@<ssh_host> -p <ssh_port> nvidia-smi
```

Your public key from step 2 is already authorised, so you don't need the `private_key` field. It is a platform-generated key, returned only by this endpoint, for clients that didn't supply their own.

The image's environment carries over into SSH sessions, so `python` and `conda` work exactly as the image defines them. Persistent storage is mounted at `/workspace`.

## 6. Stop it (this stops billing)

```bash
curl -s -X DELETE "$GC_API/platform/deployments/$DEPLOYMENT_ID" -H "Authorization: Bearer $GC_KEY"
```

Billing is per minute, so you pay only for the time it ran.

## Next

- [GPU rental reference](https://www.green-compute.com/docs/gpu-rental.md): every field, ports, disk, resume, 5090 notes
- [Errors](https://www.green-compute.com/docs/errors.md): what each status code means and how to recover
- [Inference API](https://www.green-compute.com/docs/inference.md): OpenAI-compatible chat completions