OpenRelay API Documentation

Bring your GPU hardware online as OpenRelay capacity with a single command and start earning.

Contribute GPU hardware to the OpenRelay network: customer workloads run on your boxes and you earn a share of the usage. Onboarding a node is one command.

Before you start

You need an org that is an approved provider (isProvider enabled) and a host running Ubuntu 22.04/24.04 with root access, curl, and outbound HTTPS. For GPU capacity, the host needs NVIDIA GPU(s); for VM nodes, enable CPU virtualization (VT-x / AMD-V) and IOMMU (VT-d / AMD-Vi) in BIOS. See Provider nodes for the full hardware checklist and GPU passthrough details.

Become a provider

Apply from the dashboard (or POST /v1/orgs/{orgId}/provider/apply). Once your application is approved, your organization's isProvider flag is enabled — check it any time with GET /v1/orgs/{orgId}/provider/status.

Get your install command

In the dashboard go to Nodes → Add Node, pick the node type, GPU runtime, and pool, and it generates a ready-to-paste command with a provisioning token (vtk_…) baked in:

curl -fsSL "https://api.openrelay.inc/v1/provider/bootstrap?token=vtk_…" | sudo bash

The token self-authenticates the request — no API key needed on the node. It is shown once, can be scoped to multiple enrollments (Max Nodes), and expires on the schedule you pick.

With an org API key (vl_… — Settings → API keys, see Authentication) the bootstrap endpoint mints a single-use token on the fly. The key is sent once in the request header — it never lands on the node:

curl -fsSL -H "Authorization: Bearer $VL_KEY" \
  "https://api.openrelay.inc/v1/provider/bootstrap?pool=community" | sudo bash

Run it on the box

The installer stages the agents (sha256-verified), enrolls the node, and brings it online in your pool automatically. Re-running the exact same command is always safe — enrollment is idempotent per hostname.

Verify the node is online

Watch the Nodes tab in the dashboard (it updates live), or:

curl -fsSL -H "Authorization: Bearer $VL_KEY" \
  https://api.openrelay.inc/v1/orgs/$VL_ORG/provider/nodes | jq .

A healthy node shows as ready in its pool. From then on it keeps itself up to date automatically — no manual maintenance needed. To confirm everything on the box, run sudo vectorlay-node-doctor (see Provider nodes).

Options

Append these query params to the bootstrap URL:

Param	Default	Meaning
`token`	—	A pre-minted provisioning token (`vtk_…`); replaces the API-key header. Pool, node type, and quota ride on the token, so the other params below don't apply.
`gpu`	`0`	`1`/`true` installs the gVisor/nvproxy container-GPU runtime. Leave it off for VM nodes (QEMU/VFIO passthrough) — their GPUs are detected automatically.
`pool`	`community`	The pool the node lands in (API-key flow only).
`nodeType`	`persistent`	`persistent` or `spot` (API-key flow only).
`name`	—	Optional label for the minted token (API-key flow only).

For example, a spot container-GPU node in a named rig:

curl -fsSL -H "Authorization: Bearer $VL_KEY" \
  "https://api.openrelay.inc/v1/provider/bootstrap?gpu=1&pool=community&nodeType=spot&name=rig-7" \
  | sudo bash

Security

Neither credential persists on the node: the API key is used once in the request header, and the provisioning token is spent at enrollment (the node receives its own durable identity instead). Installer responses are never cached, and every artifact is sha256-pinned.

Managing nodes & tokens

Mint provisioning tokens from the dashboard (Nodes → Add Node) or POST /v1/orgs/{orgId}/provider/tokens.
List / revoke tokens: GET and DELETE /v1/orgs/{orgId}/provider/tokens.
List your provider nodes: GET /v1/orgs/{orgId}/provider/nodes.

See the Providers endpoints in the API reference for full request/response shapes.

Earnings

You earn a share of the usage your hardware serves, settled monthly. Earnings and utilization are visible in the provider dashboard.

For GPU passthrough setup, the vectorlay-node-doctor health check, and how nodes behave across reboots, updates, recycling, and decommissioning, see Provider nodes.

Troubleshooting

Symptom	Cause
`403 NOT_A_PROVIDER`	The org isn't an approved provider yet.
`403 TOKEN_REVOKED` / `TOKEN_EXHAUSTED`	The provisioning token was revoked, or all its enrollments are used — mint a new one.
`401`	Bad, missing, or expired API key / provisioning token.
Install didn't finish	Re-run the command — it's always safe to retry.

Providers

On this page