Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceComputeVMs

Restart a VM

Reboots a running VM in place, or starts a stopped or failed VM or pod again on the node that holds its disk or volume; a running pod's container is recreated. A stopped or failed VM answers 503 VM_NODE_BUSY when its node has too few free GPUs of the VM's model, a GPU it needs has failed, or too little disk, RAM or CPU, to take it back, and the message names which (a failed GPU by its address); try later, or create a new VM to place elsewhere. A running VM or pod is never rebooted on a GPU that has failed: it answers 503 VM_NODE_BUSY or POD_NODE_BUSY naming the failed GPU, and the message says when stopping it and starting it again would place it on healthy GPUs of its node. A stopped or failed pod re-claims its GPUs on that node (503 POD_NODE_BUSY when that node's GPUs are taken, 503 INSUFFICIENT_IP_CAPACITY when the pod's InfiniBand fabric has no free address; 409 POD_NODE_OFFLINE when the node is offline, POD_NODE_NO_INFINIBAND when the org is enabled for InfiniBand but the node's agent predates it, POD_NODE_NO_AMD_GRANT when the pod's GPU model is AMD but the node's agent is below the level that grants AMD GPUs, POD_STOPPING while the previous run is still tearing down). Recreating a running pod's container resets its filesystem and keeps /workspace.

Required permission

Requires the compute.operate permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl vms restart <id>
POST
/v1/vms/{id}/restart

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

id*string

Response Body

OK

application/json
  1. response
id*string
organizationId*string
name*string
status*string

deploying, running, stopped, failed, terminated, or interrupted; a row can also carry the queued status pending. interrupted means it served and is not serving now: it keeps its node, GPU and disk, and is not billed. A VM is interrupted while its node is offline and resumes when the node returns; a pod is interrupted for that and for losing its supervisor or its job on a live node, which the platform recovers by re-submitting it. After 7 days interrupted a VM is stopped (disk kept) and a pod is deleted.

statusReason?string

Cause of the current status. The machine-readable values are "node_lost" (the host went offline and is expected back, so the disk is preserved), "node_removed" (the host was decommissioned, so the disk is gone and a restart deploys fresh elsewhere), "vm_exited", "user_stopped", "user_terminated", "user_restarted", "spot_reclaimed_by_capacity_owner", "spot_preempted_for_reservation_tenant", "auto_stopped_insufficient_balance", "auto_stopped_account_suspended", "auto_stopped_organization_deleted", the prefix "container failed to start: " followed by the container runtime's own message, and on a running workload the prefix "node leaving at " followed by the RFC 3339 time its host is removed, when the workload ends with node_removed. Anything else is free text for a human to read.

gpuModelId?string
gpuCount?integer
endpointUrl?string
volumeGb?integer

pods only: size in GB of the pod's persistent /workspace volume.

public?boolean

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

createdAt?string
provisioningStage?string
resourceSize?string
tier?string
diskSizeGb?integer
gpuModelName?string
gpuManufacturer?string

GPU vendor from the catalog, the same value as GpuModel.manufacturer (NVIDIA, AMD); absent on a CPU-only row

pricePerHourCents?integer
serviceType?string

managed-service tag; empty for a plain VM

managedBy?string

platform owner of this row ("serving" = inference serving replica, read-only on customer surfaces); empty for a customer-launched VM

capabilityTier?string

compute-fabric capability tier (e.g. "pod"); empty for a plain VM

computeClass?string

compute-fabric purchase option (on_demand; pods created before the rename carry the legacy reserved or interruptible values); empty for a plain VM

imageUrl?string

tenant container image (pods)

Example Request
curl -X POST 'https://api.openrelay.inc/v1/vms/string/restart'
Example Response
{  "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",  "gpuManufacturer": "string",  "pricePerHourCents": 0,  "serviceType": "string",  "managedBy": "string",  "capabilityTier": "string",  "computeClass": "string",  "imageUrl": "string"}

Stop a VM POST

Stops the workload and releases its GPU. A VM keeps its disk; a pod keeps its /workspace volume and its node, and can be started again with restart. While stopping VMs is switched off for the organization, a VM stop answers 409 STOP_DISABLED: terminate the VM, or leave it running. Pods are not affected.

Terminate a VM POST

Terminates a VM or pod for good: its workload stops, its GPUs are released, its usage session closes and its disk is deleted. A repeat terminate answers 200.