The worker protocol

The server side is lib/worker/core.ts, lib/worker/route.ts and app/api/worker/*. The client side is mac/MLX/Core/API.swift. Where the two disagree, the server is what counts.

#Signing a request

Every request carries one header:

x-mlx-device: <pk>|<ts>|<sig>

The signed message is canonical JSON (keys sorted, no spaces), built by deviceRequestMessage:

{"body":"<sha256 hex of the request body>","chain":"<chain id>","device":"<pk>","method":"POST","path":"/api/worker/hello","ts":<ts>,"type":"mlx-device-request"}

• body is the SHA-256 of the exact bytes sent, as hex. An empty body hashes the empty string.
• chain is the chain id from GET /api/stats (chain).
• path is the URL path only, without the host or a query.
• ts is a number, not a string.

High-S signatures are accepted (verifyDevice in lib/chain/device.ts), which is what CryptoKit makes.

import { p256 } from "@noble/curves/p256";
import { sha256 } from "@noble/hashes/sha256";
import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils";

// lib/chain/crypto.ts `canonical`: sorted keys, no whitespace
const canonical = (v) =>
  v === null || typeof v !== "object" ? JSON.stringify(v)
  : Array.isArray(v) ? "[" + v.map(canonical).join(",") + "]"
  : "{" + Object.keys(v).filter((k) => v[k] !== undefined).sort().map((k) => JSON.stringify(k) + ":" + canonical(v[k])).join(",") + "}";

const hex = (s) => bytesToHex(sha256(utf8ToBytes(s)));

export async function devicePost(path, body, secretKey) {
  const { chain } = await (await fetch("https://mlx.app/api/stats")).json();
  const pk = bytesToHex(p256.getPublicKey(secretKey, true));
  const raw = JSON.stringify(body);
  const ts = Date.now();
  const message = canonical({ type: "mlx-device-request", chain, device: pk, method: "POST", path, body: hex(raw), ts });
  const sig = p256.sign(sha256(utf8ToBytes(message)), secretKey).toCompactHex();
  return fetch("https://mlx.app" + path, {
    method: "POST",
    headers: { "content-type": "application/json", "x-mlx-device": `${pk}|${ts}|${sig}` },
    body: raw
  });
}

import CryptoKit

// MLX Node builds `message` with Signing.requestMessage (mac/MLX/Core/Canonical.swift):
// the same canonical JSON, keys sorted by UTF-16 code units like JavaScript.
let key = try SecureEnclave.P256.Signing.PrivateKey()
let hex = { (d: Data) in d.map { String(format: "%02x", $0) }.joined() }
let pk = hex(key.publicKey.compressedRepresentation)
let sig = hex(try key.signature(for: Data(message.utf8)).rawRepresentation)  // SHA-256 inside
request.setValue("\(pk)|\(ts)|\(sig)", forHTTPHeaderField: "x-mlx-device")

#What the server checks

signedDevice and deviceRoute check, in this order:

Once only. Each signature is accepted once (wk:sig:<sig>, kept for a while). Resending the same signed request is refused, so every request needs a new ts and signature.

Anyone can make a P-256 key and sign. An unknown key gets answers, but its status isn't kept until it is linked to a wallet (or has redeemed a beta invite), and it gets no jobs.

#Rate limits

Limits count requests per Mac and per route, a minute at a time, on each server instance (limited in lib/worker/core.ts).

A device route that names no limit gets 30 a minute (DEVICE_ROUTE_PER_MINUTE). Results have a second limit of their own: 300 a minute per Mac, counted across instances (see Results).

#POST /api/worker/hello

The heartbeat. MLX Node sends it on a timer, at once when something changes (a pause, leaving the wallet), and shortly after it carries out remote commands. Every field is cleaned on the way in (hello in lib/worker/core.ts): strings are cut short and control characters removed, numbers are clamped, and anything of the wrong type is dropped.

Of these, only chip, hw, hwid, state and reason can change what the Mac earns (hwid: one Mac is paid once an hour, however many device keys it has). tokPerSec, calibration, today and tps are shown in apps and never paid on.

The heartbeat also marks the current minute as available when the state is eligible, removes the acknowledged commands, and, for a linked Mac, stores its approximate city for MLX World (from the request's location headers; no IP address is kept).

#The reply

earning (earningView in lib/compute/rewards.ts). Amounts are MLX base units as strings unless noted.

#POST /api/worker/job

Asks for the next job.

{ "memoryGB": <the Mac's unified memory, GB> }

memoryGB decides which fixed test jobs fit. MLX Node 0.10 also sends open: the slice its last result was asked to open (the body of POST /api/worker/open), so it costs no extra round trip. The server may hold the request before it answers: for a free seat's throttle wait, and for the hand-out pacing (200 ms between hand-outs). See Jobs and checks.

The job is recorded as handed to this Mac. Asking again before answering returns the same job.

A dedicated seat may get a paid job from the Compute API instead: id paid-<18 hex>, kind: "paid", the same fields and the same model. The Mac runs it like any other job and returns it with POST /api/worker/result; its text becomes the paying request's answer.

#POST /api/worker/result

Returns a finished or interrupted job.

MLX Node treats a 409 like a lost reply: it asks for the next job. Verdicts for the other Macs on the same job are written after the reply, so the Mac doesn't wait for them.

#POST /api/worker/open

MLX Node 0.10: the slice of its last run that the result's reply asked for. MLX Node sends the same object as open in its next job request instead; this endpoint takes it on its own.

Replies { ok: true }, or 409 "Nothing to open for that job" when it isn't the slice this Mac was asked for (or it was already opened). A wrong path is recorded as a failed check at once; the MLP is checked by the server within a few minutes.

#POST /api/worker/feedback

Feedback from MLX Node's Settings: { text, diagnostics? }. Diagnostics are opt-in, and never contain prompts, outputs or file paths. Replies { ok: true }, 400 "Write something first" for an empty text, or 403 when the server has never kept a heartbeat from this Mac.

#POST /api/worker/redeem

Redeems a Mac beta invite code on this Mac: { code }. Replies { ok: true, wave } or 400 with the reason. An invite is no longer needed to get jobs.

#Device lookup

Unsigned and public: which wallet a device is linked to. MLX Node polls it after it opens the wallet to link.

{"linked":false,"account":null,"at":null}

at is the time of the link (ms) when there is one. MLX Node waits for it to grow.

#Related

• POST /api/log/cosign is signed the same way: a Mac cosigning a checkpoint. See Witnesses.
• What the server does with the work: Jobs and checks and Compute rewards.