Worker protocol

Workers talk to the server over a single WebSocket at wss://app.meris.network/api/worker/ws. Messages are JSON objects with a type field. This page is for people auditing the worker or writing their own.

Pairing

Pairing happens once, over HTTPS, before any WebSocket:

POST /api/worker/pair
{ "code": "K7QD-3MXA", "name": "desktop" }

200 { "token": "mw_…", "workerId": "…", "name": "desktop" }

Codes come from the dashboard, are single-use and expire after 15 minutes. The server stores only the SHA-256 hash of the token.

Session

The first message after connecting must be hello:

{
  "type": "hello",
  "token": "mw_…",
  "version": "0.1.0",
  "os": "linux 6.8.0 x64",
  "gpu": { "name": "<gpu name>", "vendor": "nvidia", "vramMb": 24564, "driver": "560.35", "count": 1 },
  "runtime": "gpu",
  "models": [],
  "timezone": "Europe/Paris"
}

The server answers welcome with the device's id, name and current config:

{
  "type": "welcome",
  "workerId": "72ae4903-07f2-4811-961f-d1c1864e6360",
  "name": "desktop",
  "config": { "allocation": 100, "lentVramMb": 24564, "concurrency": 2, "paused": false, "autoYield": true }
}

The config can carry more fields; workers ignore the ones they do not use. Whenever the owner changes a setting in the dashboard, the server pushes { "type": "config", "config": … }.

Worker to server

Type	Fields	When
status	gpuUtil, vramUsedMb, tempC, busy	Every 5 s
error	id, message	When the worker declines or fails a job

busy is true when the GPU is working hard with no Meris work on it; with stepping aside on, the server stops using the card while it is set.

Server to worker

Type	Fields	Meaning
job	id and the workload	Work for this GPU. The current worker declines it with error; running lab workloads needs a newer worker version.
cancel	id	Stop this job now
config	config	Settings changed
error	code, message	unpaired or outdated; the connection closes next

Close codes

Code	Meaning	Worker behaviour
4001	Unknown or removed device	Exits; pair again
4002	Replaced by a newer connection with the same token	Exits
4003	Worker version too old	Exits; reinstall
other	Network problem, server restart	Reconnects after 1 s, doubling up to 30 s

The server pings every 20 seconds and drops connections that stop answering.