Menu
Platform
AI
App store purchases
Database
Flags
Jobs and cron
Localization
Monitoring
Notifications
Payments
Queues
Sandboxes
Webhooks
Getting Started
Authentication
KV Store
Deploy & Infrastructure
Reference
Runner lifecycle
What a runner is between being leased and being wiped.
Today this runs on the management API
Your runners are listed with GET /v1/runners, which shows each status, and a runner's jobs with GET /v1/runners/{id}/jobs; see the Runners quickstart. The runners get and runners list calls below are not served at api.sylphx.com.
A Runner is one runner: one machine for exactly one job, on its own Sandboxes lease, released and wiped after. It is the smallest unit in the product, and it is disposable by design — a runner that has finished a job has no further use for anything the job left behind, so nothing is kept.
Runners is its only writer. A caller reads a runner to find out what ran, when and how it ended; nothing on the caller's side creates one or pushes work onto one.
#The five states
state is the lifecycle state, and it is observed rather than set:
| State | What it means |
|---|---|
provisioning | The machine is being leased and made ready. No job has started. |
idle | The machine is waiting for a job. |
busy | The machine is running a job. |
finished | The job ended. |
failed | It never ran a job. |
The two middle states are the ones a scale set reports as counters — runners
running a job and runners waiting for a job — so busy and idle are the
same fact read at the runner and at the registration. finished is a job that
ran; failed is a job that never did.
#Why a runner never ran a job
When state is failed, failure says why in one typed word:
| Reason | What it means |
|---|---|
no_capacity | No capacity could be leased for it. |
class_not_offered | Its class is not offered where it had to run. |
capability_missing | A capability its class needs is missing. |
boot_failed | Its machine did not finish booting. |
The reason is an enum rather than a message, and it is about the machine
rather than about the work: failure is set only when the runner never ran a
job, so a runner that ran one ends finished.
#What the record carries
A runner is a record of one job, and the fields are read-only:
| Field | Type | What it is |
|---|---|---|
state | RunnerState | The lifecycle state. One of provisioning, idle, busy, finished, failed. |
failure | RunnerFailure | Why it never ran a job, when state is FAILED. One of no_capacity, class_not_offered, capability_missing, boot_failed. |
runner_class | string | The class it runs as. |
lease | string | Its Sandboxes lease. |
repository | string | The repository of its job, owner/name. |
job_uri | string | The job on the forge. |
start_time | timestamp | When its job started. |
end_time | timestamp | When its job ended. |
lease is the link to the machine underneath: the Sandboxes lease is what the
job actually ran on, and it is released and wiped when the job ends. The
repository and job_uri pair is the link back to the forge, which is where
the job's own logs and result live.
#Reading one
A runner is read by name, and its name sits under the scale set that produced it:
sylphx runners runners get orgs/acme/scale_sets/scale-set/runners/runnercurl "https://api.sylphx.com/v1/orgs/acme/scale_sets/scale-set/runners/runner" \
-H "Authorization: Bearer $SYLPHX_API_KEY"const response = await sylphx.runners.runners.get({ name: 'orgs/acme/scale_sets/scale-set/runners/runner' })The parent is the scale set, so listing a scale set's runners is the way to read what it has done:
sylphx runners runners list orgs/acme/scale_sets/scale-setBoth reads need runners:read. Every method, its scope and its examples are in
the runners reference.