
# 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](https://cruma.io/book/tron/runners.md), which already speak the protocol for you.

The protocol described here is version `v1`, the only version, as served by
[tron.cruma.io](https://tron.cruma.io). Tron also publishes it as an
[AsyncAPI 3.0](https://www.asyncapi.com/) 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:

```text
wss://tron.cruma.io/api/runners/ws
```

The connection carries no credential of its own: send no `Authorization`
header. Authenticate inside the protocol instead:

1. Create a worker key on the Runners page of Tron. The token is shown once.
2. Send `authenticate` with that token as the first frame on the connection.
3. Tron answers `authenticated` with a fresh session id, or
   `authentication_failed` and then closes the connection. A first frame that
   is not a valid `authenticate`, a wrong or revoked token, and a first frame
   that arrives late all get `authentication_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:

```text
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
```

1. **Authenticate**, then optionally **announce** the handler keys and
   concurrency you support, once.
2. **Wait** for `work`. Waiting can take as long as it takes. A `work` frame
   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.
3. **Accept** the delivery before its `accept_deadline`. Tron answers
   `accepted` with a secret, or `accept_refused` and a reason. After a refusal,
   do not run the job.
4. **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.** `work` carries an `accept_deadline`: the time Tron pushed
  the delivery plus the job's delivery timeout. An `accept` after it is refused
  with `delivery_timed_out`, and the delivery counts as failed to deliver.
- **One-time secret.** The `secret` in `accepted` is 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`. Its `outcome` is a single
  string, either `{"ok": "..."}` or `{"err": "..."}`. A second report with a
  matching secret is rejected with `not_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_recorded` carries `late`, 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:

<!-- tron-runner-protocol-example:start -->
```json
{"type":"authenticate","token":"<worker API key token>"}
```

Tron accepts the token:

```json
{"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:

```json
{"type":"authentication_failed"}
```

The runner announces its handlers and capacity, once. This step is optional:

```json
{"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:

```json
{"type":"announced"}
```

Instead, when the announcement breaks a constraint:

```json
{"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:

```json
{"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:

```json
{"type":"accept","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90"}
```

Tron returns the secret. Store it: it is never shown again. Now run the job:

```json
{"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:

```json
{"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":"..."}`:

```json
{"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:

```json
{"type":"report_recorded","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","late":false}
```

Instead, when Tron could not record the report:

```json
{"type":"report_rejected","delivery_id":"c3a91f5d-6e28-4b07-a4d2-8f1e3b5c7a90","reason":"wrong_secret"}
```
<!-- tron-runner-protocol-example:end -->

## Message reference

<!-- tron-runner-protocol:start -->
<!-- Generated by tools/tron-protocol-book.mjs from tools/tron-protocol/asyncapi.json (Tron's AsyncAPI document). Do not edit between these markers. -->

### 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` |  |
<!-- tron-runner-protocol:end -->

Back to [Runners](https://cruma.io/book/tron/runners.md), or on to [runs and their states](https://cruma.io/book/tron/runs-and-states.md).

---

- Book: [Tron (Private preview)](https://cruma.io/book/tron.md)
- Previous: [Runs and their states](https://cruma.io/book/tron/runs-and-states.md)
- Pages: [Home](https://cruma.io/home.md) · [Docs](https://cruma.io/docs.md) · [Pricing](https://cruma.io/pricing.md) · [Share localhost](https://cruma.io/share-localhost.md) · [Webhook testing](https://cruma.io/webhook-testing.md) · [Homelab](https://cruma.io/homelab.md) · [AI coding agents](https://cruma.io/ai-coding-agents.md) · [Cruma vs ngrok](https://cruma.io/ngrok-alternative.md) · [Cruma vs Cloudflare Tunnel](https://cruma.io/cloudflare-tunnel-alternative.md) · [Blog](https://cruma.io/blog.md)
