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
Runners
What a runner is, and what a scale set registers.
Today this runs on the management API
Self-hosted runners are registered with POST /v1/runners and read with GET /v1/runners on the management API; the Runners quickstart shows them. The scale_sets and runners collections in the API reference 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. Nothing carries over from one job to the next, and Runners is its only writer — a caller reads a runner, never creates one.
Today Runners runs GitHub Actions jobs for customer repositories: a workflow that asks for one of our classes is answered with a machine from here.
#A scale set is the registration
A ScaleSet registers one runner class on one Sylphx Runners installation. That registration is what the forge holds and what a job is matched against. Runners holds the message session between the installation and itself with one fenced holder, so the session is delivered to one holder and not two.
GitHub matches jobs to its runners; Runners keeps no global queue of its own. There is no list of pending work on our side that could disagree with the forge about what is waiting.
#The parts you set
| Field | Type | What it is |
|---|---|---|
connection | string | The Sylphx Runners installation Connection. Required. |
runner_class | string | The class, sylphx-<os>-<size>, for example sylphx-linux-standard. It is the label a workflow asks for. Required. |
runner_group | string | The forge runner group to register in; the installation’s default group by default. |
max_runners | int32 | Concurrent runners at most; 0 means the plan’s limit. |
Everything else on a scale set is observed rather than set: whether the registration is Ready, how many of its runners are busy and how many are idle, and the region whose holder owns the message session. Scale sets covers those, and Runner lifecycle covers the machine that a single job gets.
#Every name is a path
A scale set and its runners are addressable under one name, and the same name works in the API, the CLI and the console:
- Scale set
- orgs/{org}/scale_sets/{scale_set}
- Scale set id
- rss_<cell><ulid>
- Runner
- orgs/{org}/scale_sets/{scale_set}/runners/{runner}
- Runner id
- rnr_<cell><ulid>
An id is never reused. runners:read covers reading a scale set and its
runners; everything that changes a scale set needs runners:write.