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:
FieldTypeDescription
max_concurrent_jobsintHow many jobs this runner executes in parallel
cpu_coresintAvailable CPU cores
memory_gbfloatAvailable memory in GB
gpu_availableboolWhether a GPU is available
supported_simulation_typesstring[]Simulation type tags this runner accepts
These are visible via GET /runners/{runner_id}.

​
Runner status

StatusMeaning
IdleConnected and ready, no active jobs
BusyExecuting one or more jobs
OfflineNo heartbeat received — runner is unreachable
MaintenanceDrained — connected but not accepting new jobs

​
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. 
# Drain
curl -X POST https://api.lynx.tetryx.io/runners/<runner-id>/drain

# Resume when ready
curl -X POST https://api.lynx.tetryx.io/runners/<runner-id>/resume
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.