Skip to main content
A runner is a worker process you deploy on your own infrastructure. It connects to the Lynx platform, picks up queued jobs, executes your simulation, and reports results back. You control where runners run — on bare metal, VMs, or Kubernetes. Lynx manages job distribution and tracks results.

​
What a runner does

  1. Connects to the Lynx platform using your provided credentials
  2. Registers itself with its capabilities (CPU, memory, concurrency limit)
  3. Polls for queued jobs and claims them
  4. Executes the simulation workload
  5. Reports job outcomes (complete or failed) back to Lynx
  6. Sends heartbeats so the platform knows it is alive

​
Runner capabilities

Each runner declares its capabilities at startup: These are visible via GET /runners/{runner_id}.

​
Runner status

​
Drain and resume

Draining a runner stops it from accepting new jobs without interrupting work already in progress. Use this before taking a machine offline for maintenance.
While drained, the runner’s status shows Maintenance. In-flight jobs run to completion before the runner goes quiet.

​
Scaling the pool

You can run any number of runners concurrently. Lynx distributes jobs across all active runners automatically — no additional configuration is required when adding or removing runners. Each runner must have a unique runner_id.

​
Retry handling

If a runner fails a job and the job has retries remaining (retries < max_retries), Lynx automatically requeues it. The next available runner picks it up. You do not need to handle requeuing yourself.

​
Deployment

See Runner Deployment for startup flags and Kubernetes setup.