OpenRelay API Documentation

Compute-fabric pod (BYO container image + SSH keys): a hardened GPU container on a whole native-driver GPU. Admission claims a free device-request GPU unit (see listPodCapacity for what is claimable), snapshots the on-demand rate immutably onto the pod, and drives the guest workflow.

Command line

The orl CLI wraps this endpoint:

orl pods create --image <image>

Authorization

apiKey

AuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request to create a compute-fabric pod: a RunPod-style bring-your-own container image + SSH keys guest. A focused subset of CreateVmRequest (no qcow2 template / kernel modules / privileged mode).

name?string

gpuModelId?string

computeClass?string

purchase option. on_demand (pay per second, no commitment) is the only class sold; reserved is a deprecated alias that is stored as on_demand. interruptible is retired and rejected with 400 COMPUTE_CLASS_RETIRED; it remains listed only until the deprecation window closes.

Default"on_demand"

Value in

"on_demand"
"reserved"
"interruptible"

image*string

tenant container image ref (required)

gpuCount?integer

how many whole GPUs this pod gets. All of them are claimed on ONE node and passed to the container together; the pod is priced for gpuCount GPUs. Omitted = 1. A request larger than any single node can currently tile is rejected at admission (see freeUnits / maxGpuCount on /v1/pods/capacity).

Range1 <= value <= 8

Default1

sshKeys?array<string>

tenant SSH public keys injected into the guest

envVars?

httpPort?integer

in-guest HTTP port exposed on the endpoint

Default80

shmSizeGb?integer

size of the pod's private /dev/shm in GiB (docker --shm-size). Optional; the maximum is half the pod's memory limit on its placement node (itself the pod's GPU-proportional share of node RAM), and a larger value is rejected at admission. Omitted lets the platform pick a safe default: that same maximum for a pod that owns its whole node, 2 GiB per GPU (capped at the maximum) for a shared multi-GPU pod, and docker's default for a shared single-GPU pod. Raise this when a multi-GPU NCCL / PyTorch DataLoader workload needs more shared memory than the default.

Range1 <= value <= 8192

public?boolean

true = open endpoint (no data-plane auth); default false requires an org API key

Defaultfalse

volumeGb?integer

size in GB of the pod's persistent volume, mounted read-write at /workspace. Omitted = 50. The volume lives on the pod's node and is kept across stop, start, restart, container crashes, node reboots and interruptions; it is deleted only when the pod is deleted (or after 7 days interrupted with its node gone). Everything outside /workspace is the container's own filesystem and is reset whenever the container is recreated. Fixed at create; there is no resize.

Range10 <= value <= 1024

Response Body

`application/json`

curl -X POST "https://example.com/v1/pods" \  -H "Content-Type: application/json" \  -d '{    "name": "cuda-devbox",    "gpuModelId": "rtx-4090",    "computeClass": "on_demand",    "image": "ghcr.io/acme/cuda-devbox:latest",    "sshKeys": [      "ssh-ed25519 AAAA... user@host"    ],    "httpPort": 8000,    "envVars": {      "HF_TOKEN": "hf_xxxxxxxx"    }  }'

{  "id": "string",  "organizationId": "string",  "name": "string",  "status": "string",  "statusReason": "string",  "gpuModelId": "string",  "gpuCount": 0,  "endpointUrl": "string",  "volumeGb": 0,  "public": true,  "createdAt": "string",  "provisioningStage": "string",  "resourceSize": "string",  "tier": "string",  "diskSizeGb": 0,  "gpuModelName": "string",  "pricePerHourCents": 0,  "serviceType": "string",  "managedBy": "string",  "capabilityTier": "string",  "computeClass": "string",  "imageUrl": "string"}

Create a pod

Command line

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`