
# Runners

A runner is your program that keeps a WebSocket connection open, accepts work
from Tron and reports its result. The work runs in your environment rather than
inside Tron.

## Create and protect a worker key

Open **Runners**, name the machine or deployment, and choose **Create worker
key**. The token is shown once: copy it into your secrets store before closing
the message. Tron stores only a one-way check of the secret, so a lost token
cannot be recovered. Revoke a key from the same page to stop it authenticating.

Connect to:

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

The session follows four main steps:

1. **Authenticate** with the worker key as the first message.
2. **Wait** for a work message containing the delivery, run and job ids, job
   name, due time and acceptance deadline.
3. **Accept** the delivery before its deadline. Tron returns a one-time secret.
4. **Report** exactly one `ok` or `err` result with that secret.

The Runners page contains the complete message reference. A runner can also
announce the handler names it supports and how many deliveries it can run at
once; a job selects a handler.

## Write a runner

Tron publishes a package for Rust, Python, TypeScript, .NET and Go. Install one
and you only write the handler: the package authenticates with your worker key,
announces the handlers you register, accepts each delivery straight away, keeps
the one-time secret until the result is reported, reconnects after a dropped
connection, and reports your handler's `Ok` or `Err` result once. Each example
below reads Tron's address, the worker token and a directory for delivery
secrets from the `TRON_URL`, `TRON_WORKER_KEY` and `TRON_SECRET_DIR` environment
variables, and is run by its package's own tests. Keep the secrets directory
across restarts so a result can still be reported afterwards.

A runner with more than one handler cannot receive deliveries yet, because a
work message does not say which handler it is for. Register one handler per
runner process. To speak the protocol without a package, follow the message
reference on the Runners page.

<!-- tron-runner-examples:start -->
### Rust

Package: [`cruma-tron-runner`](https://crates.io/crates/cruma-tron-runner) on crates.io.

```text
cargo add cruma-tron-runner
```

```rust
use cruma_tron_runner::{Endpoint, FileSecretStore, Runner};

let endpoint = Endpoint::from_base_url(&std::env::var("TRON_URL")?)?;
let runner = Runner::builder(endpoint, std::env::var("TRON_WORKER_KEY")?)
    .secret_store(FileSecretStore::new(std::env::var("TRON_SECRET_DIR")?)?)
    .on("send-report", |job| async move {
        // Ok marks the run succeeded and Err marks it failed; both carry a message.
        Ok(format!("sent the report for {}", job.job_name))
    })
    .connect()
    .await?;

// ... keep the process alive; when it is told to shut down:
// finish in-flight work, report it, then close
runner.stop().await;
```

### Python

Package: [`cruma-tron-runner`](https://pypi.org/project/cruma-tron-runner/) on PyPI.

```text
pip install cruma-tron-runner
```

```python
import os

from tron_runner import Delivery, FileSecretStore, Ok, Outcome, Runner

runner = Runner(
    os.environ["TRON_URL"],
    os.environ["TRON_WORKER_KEY"],
    secret_store=FileSecretStore(os.environ["TRON_SECRET_DIR"]),
)

async def send_report(delivery: Delivery) -> Outcome:
    # Ok marks the run succeeded and Err marks it failed; both carry a message.
    return Ok(f"sent the report for {delivery.job_name}")

runner.register("send-report", send_report)
async with runner:
    ...  # keep the process alive; leaving this block finishes in-flight work, reports it, then closes
```

### TypeScript

Package: [`@cruma-io/tron-runner`](https://www.npmjs.com/package/@cruma-io/tron-runner) on npm.

```text
npm install @cruma-io/tron-runner
```

```ts
import { FileSecretStore, ok, Runner } from "@cruma-io/tron-runner";

const runner = new Runner({
  url: process.env.TRON_URL!,
  token: process.env.TRON_WORKER_KEY!,
  secretStore: new FileSecretStore(process.env.TRON_SECRET_DIR!),
});

runner.handle("send-report", (delivery) => {
  // Ok marks the run succeeded and Err marks it failed; both carry a message.
  return ok(`sent the report for ${delivery.jobName}`);
});

await runner.start();
// ... keep the process alive; when it is told to shut down:
await runner.stop(); // finish in-flight work, report it, then close
```

### .NET

Package: [`Cruma.Tron.Runner`](https://www.nuget.org/packages/Cruma.Tron.Runner) on NuGet.

```text
dotnet add package Cruma.Tron.Runner
```

```csharp
using Cruma.Tron.Runner;

await using var runner = new RunnerClient(new RunnerClientOptions
{
    TronUrl = new Uri(Environment.GetEnvironmentVariable("TRON_URL")!),
    Token = Environment.GetEnvironmentVariable("TRON_WORKER_KEY")!,
    SecretDirectory = Environment.GetEnvironmentVariable("TRON_SECRET_DIR")!,
});

runner.Handle("send-report", (delivery, cancellationToken) =>
{
    // Ok marks the run succeeded and Err marks it failed; both carry a message.
    return Task.FromResult(Outcome.Ok($"sent the report for {delivery.JobName}"));
});

await runner.ConnectAsync();

// ... keep the process alive; when it is told to shut down:
await runner.StopAsync(); // finish in-flight work, report it, then close
```

### Go

Package: [`github.com/umbra-yurei/tron-runner-sdk/packages/go`](https://pkg.go.dev/github.com/umbra-yurei/tron-runner-sdk/packages/go) on pkg.go.dev.

```text
go get github.com/umbra-yurei/tron-runner-sdk/packages/go
```

```go
store, err := tronrunner.NewFileSecretStore(os.Getenv("TRON_SECRET_DIR"))
if err != nil {
	return err
}
runner, err := tronrunner.New(tronrunner.Config{
	BaseURL:     os.Getenv("TRON_URL"),
	Token:       os.Getenv("TRON_WORKER_KEY"),
	SecretStore: store,
})
if err != nil {
	return err
}

runner.Handle("send-report", func(ctx context.Context, d tronrunner.Delivery) tronrunner.Outcome {
	// Ok marks the run succeeded and Err marks it failed; both carry a message.
	return tronrunner.Ok("sent the report for " + d.JobName)
})

if err := runner.Connect(ctx); err != nil {
	return err
}

// ... keep the process alive; when it is told to shut down:
return runner.Stop(context.Background()) // finish in-flight work, report it, then close
```
<!-- tron-runner-examples:end -->

## How work fans out

| Mode | Delivery rule |
| --- | --- |
| One runner | One eligible runner wins the work. |
| Every connected runner | Every connected eligible runner receives it. By default every runner that was sent the work must report `ok`; an optional minimum success count lowers that bar. |
| At least N | Tron waits for N eligible runners, sends to all of them, and succeeds after N successful results. |
| At most N | Tron sends to no more than N eligible runners and succeeds after one successful result. |

If no capable runner accepts before the delivery window closes, the run becomes
**Failed to deliver**. A job configured to defer missed occurrences can keep a
limited number pending until a capable runner connects.

Next: [read the resulting run](https://cruma.io/book/tron/runs-and-states.md).

---

- Book: [Tron (Private preview)](https://cruma.io/book/tron.md)
- Previous: [Webhook targets](https://cruma.io/book/tron/webhook-targets.md)
- Next: [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)
