Runner protocol
This chapter is the complete reference for how a runner talks to Tron over a WebSocket. You need it only when you write a runner without one of the Tron runner packages, which already speak the protocol for you.
The protocol described here is version v1, the only version, as served by
tron.cruma.io. Tron also publishes it as an
AsyncAPI 3.0 document at
https://tron.cruma.io/api/asyncapi.json, which needs no sign-in. The frame
tables in the message reference at the end of this chapter are generated from
that document, so they list exactly what Tron speaks.
Connect and authenticate
Open a WebSocket connection to:
wss://tron.cruma.io/api/runners/ws
The connection carries no credential of its own: send no Authorization
header. Authenticate inside the protocol instead:
- Create a worker key on the Runners page of Tron. The token is shown once.
- Send
authenticatewith that token as the first frame on the connection. - Tron answers
authenticatedwith a fresh session id, orauthentication_failedand then closes the connection. A first frame that is not a validauthenticate, a wrong or revoked token, and a first frame that arrives late all getauthentication_failed.
Every frame, in both directions, is one JSON text message: an object whose
type field names the frame. Binary messages are not frames. Tron decodes only
the frames and fields defined in the message reference: an unknown type, a
missing or extra field, or an unknown protocol_version is answered with
protocol_error and the reason malformed_message.
The session
A connection that has authenticated is a runner session. From connecting to the final report:
runner Tron
| authenticate -------------------------> |
| <---------------------- authenticated | or authentication_failed, then close
| announce (optional, once) ------------> |
| <------------------------ announced |
| ... wait for work ... |
| <----------------------------- work | one delivery of one run
| accept -------------------------------> | straight away, before accept_deadline
| <----------------------- accepted | carries the one-time secret
| ... run the job ... |
| report, with the secret --------------> | one final ok or err result
| <------------------- report_recorded | or report_rejected
- Authenticate, then optionally announce the handler keys and concurrency you support, once.
- Wait for
work. Waiting can take as long as it takes. Aworkframe names one delivery and carries no job input or payload: only ids, the job name, the handler key it was dispatched for and two times. - Accept the delivery before its
accept_deadline. Tron answersacceptedwith a secret, oraccept_refusedand a reason. After a refusal, do not run the job. - Run the job, then report exactly one result with the secret.
Between those steps Tron may also send protocol_error. It answers any frame
that breaks the protocol after authentication, names a reason, and leaves the
connection open.
Limits and rules
| Rule | Value |
|---|---|
Time to send authenticate after connecting | 10 seconds by default |
Time to accept a delivery | until the accept_deadline in work: the push time plus the job's delivery timeout |
| Final reports per delivery | exactly one |
| Result message kept by Tron | 16,384 bytes (16 KiB) by default |
announce per connection | at most one |
The authentication timeout and the result message limit are Tron
configuration. The values above are the defaults;
GET https://tron.cruma.io/api/config returns the values a running Tron uses
as runner_authentication_timeout_seconds and
runner_result_message_limit_bytes, and runner_socket_path gives the
WebSocket path.
- Accept deadline.
workcarries anaccept_deadline: the time Tron pushed the delivery plus the job's delivery timeout. Anacceptafter it is refused withdelivery_timed_out, and the delivery counts as failed to deliver. - One-time secret. The
secretinacceptedis shown once, so keep it until you have reported. A report can arrive on a new connection authenticated with the same worker key, for example after the runner restarts. - One final report. A delivery takes one
report. Itsoutcomeis a single string, either{"ok": "..."}or{"err": "..."}. A second report with a matching secret is rejected withnot_in_flight. - Result message size. Tron keeps at most the limit above of the outcome's
string. A longer string is cut at a character boundary and ends with the text
[truncated by Tron], and the report is still recorded. - Late.
report_recordedcarrieslate, true when the report arrived more than the job's lateness threshold after the run was due. A late report is still recorded. - After a disconnect. Depending on the job's retry settings, losing the connection while a delivery is accepted can count as a failed attempt. Otherwise the runner can reconnect with the same worker key and still report with its secret.
Delivery modes and fan-out
The job decides how deliveries of one run relate:
| Job's delivery mode | What the runner sees |
|---|---|
one_runner | The run is pushed to a single session. If another session also tries to accept the same run, it gets accept_refused with the reason already_resolved. |
every_connected | Every connected eligible session receives its own delivery. No accept is refused because another runner accepted: every runner that accepts runs the job and reports it. |
advanced_at_least, advanced_at_most | Several sessions receive a delivery, each accepted and reported independently. The job's count decides how many successful outcomes make the run succeed. |
Legacy and announced sessions
announce is optional. A runner that never announces is a legacy session:
it still receives work for every handler key. A runner that announces is an
announced session, listed with its handler keys and concurrency capacity,
and receives work only for the keys it announced. work carries the
handler_key the job was dispatched for, so a runner with several handlers runs
the handler with that key.
Example session
One runner's session, frame by frame. The ids are made up. Every frame below is checked against Tron's AsyncAPI document by this book's tests.
The runner authenticates:
{"type":"authenticate","token":"<worker API key token>"}
Tron accepts the token:
{"type":"authenticated","session_id":"5f0c2b8e-4d1a-4c3e-9b7f-2a6d8e1f0c34","worker_api_key_id":"0b7e4c21-93d5-4f6a-8e2b-71c4d9a3f5e0"}
Instead, when the token is wrong or late, Tron sends this and closes the connection:
{"type":"authentication_failed"}
The runner announces its handlers and capacity, once. This step is optional:
{"type":"announce","announcement":{"handler_keys":["backup"],"display_name":null,"runner_version":null,"sdk_version":null,"protocol_version":"v1","concurrency_capacity":1}}
Tron keeps the announcement:
{"type":"announced"}
Instead, when the announcement breaks a constraint:
{"type":"protocol_error","reason":"invalid_announcement"}
Later, Tron pushes a run. The accept_deadline is the push time plus the job's
delivery timeout, here 30 seconds:
{"type":"work","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","run_id":"9e4d2a17-b5c8-4f3e-8a61-0d7c2e9b4f15","job_id":"2d8f6b30-7a1e-4c95-b3d4-e5f0a2c81b67","job_name":"nightly-backup","handler_key":"backup","scheduled_for":"2030-01-01T03:00:00.000Z","accept_deadline":"2030-01-01T03:00:32.000Z"}
The runner accepts straight away, before the deadline:
{"type":"accept","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90"}
Tron returns the secret. Store it: it is never shown again. Now run the job:
{"type":"accepted","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","secret":"<one-time delivery secret>"}
Instead, when Tron will not take the accept, do not run the job:
{"type":"accept_refused","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","reason":"delivery_timed_out"}
When the job is done, the runner reports its one final result, on this or on a
new connection. An err outcome looks the same with "outcome":{"err":"..."}:
{"type":"report","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","secret":"<one-time delivery secret>","outcome":{"ok":"backed up 42 files"}}
Tron records it and the delivery is finished:
{"type":"report_recorded","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","late":false}
Instead, when Tron could not record the report:
{"type":"report_rejected","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","reason":"wrong_secret"}
Message reference
Versions and compatibility
This reference describes runner protocol v1. A runner states the protocol it speaks in announce.announcement.protocol_version, a RunnerProtocolVersion. This document describes v1, the only version, and Tron decodes only the frames and fields defined here: an unknown frame type, a missing or extra field, or an unknown protocol_version is answered protocol_error with reason malformed_message. Runners that never announce are legacy sessions and stay compatible for this release. A change a v1 runner could not handle (a renamed or removed frame, field or reason value, or a new required field) is published under a new protocol_version, not made to v1, and this document's x-runner-protocol-version names the version it describes.
Frames a runner sends to Tron
authenticate
Must be the first frame on a new connection. Anything else, or no frame in time, is answered with authentication_failed and the connection is closed.
| Field | Type | Required | Meaning |
|---|---|---|---|
token | string | yes | The worker API key token shown once when the key was created on the Runners page. |
announce
Optional, at most once per connection, after authenticated: declares what this runner can do. Tron answers announced. Runners that never announce are listed as legacy sessions and still receive work.
| Field | Type | Required | Meaning |
|---|---|---|---|
announcement | RunnerAnnouncement | yes | The capabilities of this connection. |
accept
Takes on a delivery Tron pushed with work. Send it straight away, before the delivery's accept_deadline. Tron answers accepted or accept_refused.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The delivery_id from the work frame. |
report
The one final result of an accepted delivery. It may be sent on any connection authenticated with the same worker API key, for example a new one after the runner restarted. Tron answers report_recorded or report_rejected.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The delivery_id from the work frame. |
outcome | RunOutcome | yes | The job's result. |
secret | string | yes | The secret from the accepted frame for this delivery. |
Frames Tron sends to a runner
authenticated
Answers a valid authenticate. Several runner processes may authenticate with the same worker API key at once; each connection gets its own session.
| Field | Type | Required | Meaning |
|---|---|---|---|
session_id | string (uuid) | yes | Names this one connection. |
worker_api_key_id | string (uuid) | yes | The worker API key the token belongs to. |
announced
Confirms that this connection's announce was retained.
It carries no field besides type.
authentication_failed
The first frame was not a valid authenticate in time: a timeout, a malformed or non-text frame, another frame type, or an unknown, revoked or mismatched token. The connection is closed right after.
It carries no field besides type.
work
A run has been dispatched to this connection as one delivery. It carries no job input or payload: only ids, the job's name, the handler key it was dispatched for and times.
| Field | Type | Required | Meaning |
|---|---|---|---|
accept_deadline | string (date-time) | yes | accept must arrive by this time. It is the push time plus the job's delivery timeout. |
delivery_id | string (uuid) | yes | Names this delivery; echo it in accept and report. |
handler_key | RunnerHandlerKey | yes | The job's runner handler key. For a connection that announced handler keys it is one of them; a connection that never announced receives work for every key. A runner with several handlers runs the one with this key. |
job_id | string (uuid) | yes | The job that was triggered. |
job_name | string | yes | The job's name, as the owner set it. |
run_id | string (uuid) | yes | The run this delivery belongs to. |
scheduled_for | string (date-time) | yes | When the run was due. |
accepted
Answers a successful accept. Keep the secret: it is shown here once and never again, and report must echo it.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The accepted delivery. |
secret | string | yes | The one-time secret for this delivery's report. |
accept_refused
Answers an accept Tron would not take. Do not run the job.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The refused delivery. |
reason | AcceptRefusal | yes | Why it was refused. |
report_recorded
Answers a report Tron recorded. The delivery is finished.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The reported delivery. |
late | boolean | yes | True when the report arrived more than the job's lateness threshold after the run's scheduled_for. A late report is still recorded. |
report_rejected
Answers a report Tron could not record.
| Field | Type | Required | Meaning |
|---|---|---|---|
delivery_id | string (uuid) | yes | The delivery named in the report. |
reason | ReportRejection | yes | Why it was rejected. |
protocol_error
An authenticated runner sent a frame the protocol does not allow. The connection stays open.
| Field | Type | Required | Meaning |
|---|---|---|---|
reason | ProtocolViolation | yes | What was wrong. |
Types and reasons
The types the frames above refer to. A reason is always one of the listed values; Tron sends no free-text error.
AcceptRefusal
Why accept was refused.
| Value | Meaning |
|---|---|
unknown_delivery | No delivery with this id was pushed to this connection's session under an unrevoked worker API key. Accept on the connection that received the work. |
delivery_timed_out | The delivery's accept_deadline had passed, including when it had already been marked failed to deliver. |
already_resolved | This same delivery was already accepted (or is in flight) or reported, or its run was cancelled. A cancelled run's delivery stays pushed; the accept is refused because the run is cancelled. For one_runner, another delivery for this run already won the run-scoped accept race. Broadcast modes do not choose a winner. |
ProtocolViolation
How an authenticated runner broke the protocol.
| Value | Meaning |
|---|---|
malformed_message | A frame was not JSON for any runner frame (an unknown type, a missing or extra field, including a handler key that does not match the published handler-key schema), or was a binary frame. |
not_authenticated | Reserved; not sent today. A first frame other than authenticate is answered with authentication_failed. |
already_authenticated | authenticate was sent again on an authenticated connection. |
invalid_announcement | The announcement broke a constraint: zero capacity; no, too many, duplicate, blank or oversized handler keys; a blank or oversized display name or runner version; or a blank, oversized or non-semver SDK version. |
already_announced | announce was sent twice on one connection. Reconnect to replace the announcement. |
ReportRejection
Why report was rejected.
| Value | Meaning |
|---|---|
unknown_delivery | No delivery with this id belongs to the reporting worker API key, or that key is revoked. |
wrong_secret | The secret does not match the one issued in accepted, or the delivery was never accepted, so no secret was issued. |
not_in_flight | The secret matched, but the delivery already has its one final report. |
RunOutcome
The result a runner reports: exactly one of ok or err, each carrying a single string, so it serializes as {"ok": "..."} or {"err": "..."}.
| Field | Type | Required | Meaning |
|---|---|---|---|
ok | string | exactly one of | |
err | string | exactly one of |
RunnerAnnouncement
What a runner declares about its connection in announce.
| Field | Type | Required | Meaning |
|---|---|---|---|
concurrency_capacity | integer (int32) | no | Maximum concurrent work this session accepts; it must be positive. Omitted values default to 1 for compatibility with older runners. |
display_name | string | null | no | Optional human-readable name shown to the owner; a supplied value is non-blank and at most 128 bytes long. |
handler_keys | RunnerHandlerKey[] | yes | Stable handler keys the runner can execute. The set must contain 1 to 128 unique keys, each 1–128 bytes and matching [A-Za-z0-9][A-Za-z0-9_.-]*. |
protocol_version | null | RunnerProtocolVersion | no | Typed version of Tron's runner protocol understood by this session. |
runner_version | string | null | no | Optional runner implementation version, retained as display metadata; a supplied value is non-blank and at most 128 bytes long. |
sdk_version | string | null | no | Optional semantic SDK version, used by the server to report whether this session is older than a peer. A supplied value must parse as a semantic version and be non-blank and at most 128 bytes long. |
RunnerHandlerKey
Stable, validated name of a runner handler. Handler keys are durable job configuration, rather than a free-form label inferred from live sessions.
RunnerProtocolVersion
A version of the runner protocol defined by Tron.
| Value | Meaning |
|---|---|
v1 |
Back to Runners, or on to runs and their states.