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:
wss://tron.cruma.io/api/runners/ws
The session follows four main steps:
- Authenticate with the worker key as the first message.
- Wait for a work message containing the delivery, run and job ids, job name, due time and acceptance deadline.
- Accept the delivery before its deadline. Tron returns a one-time secret.
- Report exactly one
okorerrresult 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.
Rust
Package: cruma-tron-runner on crates.io.
cargo add cruma-tron-runner
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 on PyPI.
pip install cruma-tron-runner
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 on npm.
npm install @cruma-io/tron-runner
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 on NuGet.
dotnet add package Cruma.Tron.Runner
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 on pkg.go.dev.
go get github.com/umbra-yurei/tron-runner-sdk/packages/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
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.