OpenRelay API Documentation

This guide takes you from zero to a running GPU VM. The fastest path is the orl CLI; every step also shows the raw curl call so you can build the same flow into an app.

Just want the shortest possible path? Follow the CLI Quickstart, which skips curl entirely.

Get your credentials

Create an API key in the dashboard under Settings > API Keys. The key (it starts with vl_) is shown once. It is bound to your organization, the workspace that owns your keys, VMs, and balance.

orl auth login

Set the key in your shell, then look up your organization id with /v1/me (collection endpoints are nested under /v1/orgs/{orgId}/...):

export OPENRELAY_API_KEY="vl_your_api_key"

curl https://api.openrelay.inc/v1/me \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

{
  "user": { "id": "usr_…", "email": "you@example.com" },
  "memberships": [
    { "organizationId": "org_…", "role": "owner", "name": "Acme Inc" }
  ]
}

export ORG_ID="org_…"

Browse the catalog

See what GPUs are available and what they cost.

orl catalog gpu-availability get
orl catalog pricing get

curl https://api.openrelay.inc/v1/gpu-availability \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

curl https://api.openrelay.inc/v1/pricing \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

Note a gpuModelId with available capacity. You will use it next.

Launch a GPU VM

Create a VM. At minimum it needs a name; specify a GPU model and a container image to pick hardware and what runs on it.

orl deploy takes a name. Add --wait to block until it is ready, or --connect to wait and then open an SSH session:

orl deploy my-first-vm \
  --gpu-model rtx-4090 \
  --gpu-count 1 \
  --image ghcr.io/my-org/my-image:latest \
  --wait

curl -X POST https://api.openrelay.inc/v1/orgs/$ORG_ID/vms/create \
  -H "Authorization: Bearer $OPENRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-vm",
    "gpuModelId": "rtx-4090",
    "gpuCount": 1,
    "imageUrl": "ghcr.io/my-org/my-image:latest",
    "diskSizeGb": 100,
    "envVars": { "MODEL": "llama-3" }
  }'

The response includes the new VM's id and initial status.

Boot takes a few minutes while the VM provisions and starts, longer for many-GPU shapes.

Wait until it's running

--wait (or --connect) already blocked until the VM was ready. To check a VM later:

orl vms get <vm-id>

Provisioning takes a little while. Poll the VM until status is running:

curl https://api.openrelay.inc/v1/vms/$VM_ID \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

{
  "id": "vm_…",
  "name": "my-first-vm",
  "status": "running",
  "endpointUrl": "https://my-first-vm-….run.openrelay.inc",
  "pricePerHourCents": 59
}

Prefer webhooks over polling: subscribe to vm.running and get a callback the moment your VM is live.

Connect, then stop billing

Reach the box over SSH, or hit the endpointUrl your container exposes. A VM bills until you stop or terminate it.

orl vms ssh <vm-id>         # open a session
orl vms stop <vm-id>        # stop the meter, keep the disk
orl vms terminate <vm-id>   # destroy it

curl -X POST https://api.openrelay.inc/v1/vms/$VM_ID/terminate \
  -H "Authorization: Bearer $OPENRELAY_API_KEY"

Attach an SSH key to reach the box directly.

Next steps

Drive everything from the terminal → Command Line
Run an autoscaling endpoint instead of a single box → Clusters
Automate top-ups and avoid interruptions → Billing
React to lifecycle events → Webhooks
Explore every endpoint interactively → API Reference