---
title: Runners quickstart
description: Register a self-hosted runner, read it back, and read the jobs it has run.
type: tutorial
product: runners
summary: A runner registered with a one-time token, then its job list.
updated: 2026-10-01
order: 1
---

A runner is registered once with a one-time token and then runs the jobs it is
sent. This registers one, reads it back, and reads its jobs.

<Callout tone="note" title="Today this runs on the management API">
Self-hosted runners are registered with `POST /v1/runners` on the management API, as shown here. The `scale_sets` and `runners` collections of the [API reference](/docs/api/scale_sets) are not served at api.sylphx.com.
</Callout>

<Prerequisites
	items={[
		'An account and an organization',
		'The CLI signed in (`sylphx login`) or `SYLPHX_API_KEY` set',
		'A machine to run the runner on',
	]}
/>

## 1. Register the runner

A runner has a name, an operating system (`linux`, `macos` or `windows`) and an
architecture:

<CodeTabs>
	<CodeTab
		label="CLI"
		language="bash"
		code={`sylphx api POST /v1/runners -d '{"name":"build-box-1","platform":"linux","arch":"x64"}'`}
	/>
	<CodeTab
		label="cURL"
		language="bash"
		code={`curl -X POST https://api.sylphx.com/v1/runners \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"build-box-1","platform":"linux","arch":"x64"}'`}
	/>
</CodeTabs>

The answer carries the `runnerId` (`run_…`) and a `registrationToken`. The
token is shown once: store it where the runner process on your machine can read
it.

## 2. Read the runners

```bash
sylphx api GET /v1/runners
```

Each runner shows its `name`, `platform`, `arch`, `version`, `status` and
`lastSeenAt`. A new runner is `offline` until the process on your machine
connects.

## 3. Read its jobs

```bash
sylphx api GET /v1/runners/$RUNNER_ID/jobs
```

## GitHub installations

The GitHub organizations the Sylphx App is installed on are listed with:

```bash
sylphx api GET /v1/ci-settings/installations
```

## Next

<RelatedDocs
	links={[
		{
			href: '/docs/runners/runner-lifecycle',
			label: 'Runner lifecycle',
			description: 'The states one machine moves through.',
		},
		{
			href: '/docs/runners/scale-sets',
			label: 'Scale sets',
			description: 'Registering a runner class on a GitHub installation.',
		},
		{
			href: '/docs/hosting/quickstart',
			label: 'Hosting quickstart',
			description: 'Deploy an app from a repository.',
		},
	]}
/>