Cruma
DashboardDownload

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:

  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.

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

ModeDelivery rule
One runnerOne eligible runner wins the work.
Every connected runnerEvery 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 NTron waits for N eligible runners, sends to all of them, and succeeds after N successful results.
At most NTron 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.