Compute Workspace

Workers

Provision GPU workers as one async job, launch, boot the runtime, auto-register as a compute peer, and manage the compute peer registry directly.

Provision a worker

POST/v1/compute/workers?provider=lambda

Provisions a GPU worker end-to-end: launches the instance, boots the HybrIE runtime on it, and auto-registers the node as a compute peer when it comes up. This is an asynchronous job, expect roughly 20–30 minutes from request to ready.

Parameter	Type	Description
`spec`required	object	Instance launch spec, the full shape documented under instance launch. It has no defaults, so `region`, `gpu_count`, `ssh_key_names`, `use_spot` and `extra` are required alongside `offer_id`.
`env`	object	Optional environment variables passed to the runtime on the worker.

curl

curl -X POST "http://localhost:8080/v1/compute/workers?provider=lambda" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "offer_id": "<offer-id>",
      "region": "us-west-1",
      "gpu_count": 1,
      "ssh_key_names": ["<your-key-name>"],
      "use_spot": false,
      "extra": {}
    },
    "env": {"HYBRIE_API_KEY": "..."}
  }'

Response (202 Accepted):

json

{"job_id": "train-1718102400", "instance_id": "<instance-id>"}

Poll the job via GET /v1/train/jobs/:id, the same jobs registry used for training. On completion the job report includes:

Parameter	Type	Description
`instance_id`	string	The launched instance.
`ip`	string	Public IP of the worker.
`grpc_peer`	string	gRPC endpoint of the runtime on the worker.
`realtime_peer_url`	string	Realtime (WebSocket) endpoint of the runtime on the worker.
`peer_id`	string	Id of the auto-registered compute peer.

Compute peer registry

The compute peer registry tracks reachable HybrIE nodes, provisioned GPU workers, a Metal Mac on your desk, any node the runtime can route to. Provisioned workers register themselves; you can also peer-up any reachable node by hand.

Register a peer

POST/v1/compute/peers

Parameter	Type	Description
`name`	string	Human-readable peer name.
`grpc_peer`	string	gRPC endpoint of the node. At least one of grpc_peer / realtime_peer_url is required.
`realtime_peer_url`	string	Realtime endpoint of the node. At least one of grpc_peer / realtime_peer_url is required.
`instance_id`	string	Optional instance id, for peers backed by a provisioned instance.
`capabilities`	object	Optional capability metadata for the node.
`probe`	boolean	TCP-probe the given endpoints before registering. Default true.

Registration is an idempotent upsert keyed by endpoint, re-registering the same endpoint (e.g. a heartbeat re-register) updates the existing entry, and previously reported capabilities are preserved.

curl

curl -X POST http://localhost:8080/v1/compute/peers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "metal-mac-studio",
    "grpc_peer": "http://<node>:9090",
    "realtime_peer_url": "ws://<node>:8080/realtime"
  }'

List and remove peers

GET/v1/compute/peers

DELETE/v1/compute/peers/:id

Deleting a peer removes it from the registry only, it does not terminate the underlying instance. Terminate instances via DELETE /v1/compute/instances/:id.

Routing: when the realtime peer environment variables are unset, sessions fall back to the first reachable registered peer. You can also target a specific peer per request with the x-hybrie-preferred-peer-id header, see Hot-swap Inference.

Pre-stage model weights

POST/v1/models/stage

Downloads model weights onto a node ahead of traffic, so the first request doesn't pay the download cost. Returns 202 with {job_id, dest_dir}, polled via the same jobs registry.

Parameter	Type	Description
`repo_id`required	string	Model repository to stage (e.g. a Hugging Face repo id).
`dest_dir`	string	Destination directory on the node.
`name_filters`	string[]	Optional filename filters to stage a subset of the repo.

From the CLI

bash

stimulir compute peers list
stimulir compute peers add --grpc-peer <endpoint>
stimulir compute peers remove <peer-id>

For self-owned hardware topologies (local-only, hybrid, P2P mesh), see Edge Deployment.

Provision a worker#

Compute peer registry#