# Labels and machines

The `runs-on` label says which machine a job gets. `superci` alone is the default machine. To ask for something else, add `key=value` pairs after the name, each behind a slash, in any order.

```yaml
runs-on: superci/cpu=8/ram=32
```

## What a label can say

| Key | Example | Meaning |
|---|---|---|
| `cpu` | `superci/cpu=8` | Eight CPUs. Memory follows: 4 GB for each CPU. |
| `ram` | `superci/cpu=8/ram=64` | Memory in GB. |
| `disk` | `superci/disk=200` | Disk in GB. |
| `disk-speed` | `superci/cpu=8/disk-speed=1000` | The disk's speed in MiB a second, on AWS. |
| `disk-iops` | `superci/disk-iops=6000` | The disk's IOPS, on AWS. |
| `arch` | `superci/arch=arm64` | `x64` (the default) or `arm64`. |
| `os` | `superci/os=windows` | `linux` (the default) or `windows`; `macos` is [coming soon](/docs/macos). |
| `image` | `superci/image=ubuntu26` | Which Ubuntu: `ubuntu26` (26.04) or `ubuntu24`. Unset, as GitHub's `ubuntu-latest`. See below. On Modal, also an image of your own by its name (see [Providers](/docs/providers#modal)). |
| `gpu` | `superci/gpu=any` | Any GPU, or one by name: `gpu=l4`. |
| `family` | `superci/cpu=32/family=m8a` | Only this AWS machine family, or several: `family=m8a+r8a`. See below. |
| `scratch` | `superci/scratch=ramdisk` | Where what a job writes most is kept: `ramdisk` (in memory) or `localdisk` (a machine with an NVMe disk of its own). AWS, Linux. |
| `provider` | `superci/provider=aws` | Only this provider: `aws`, `cloudflare` or `modal`, each of its runners in the order's order. |
| `spot` | `superci/spot=false` | Never a spot machine. See [Spot machines](/docs/spot-machines). |
| `docker-cache` | `superci/image=ubuntu26/docker-cache=false` | The [Docker image cache](/docs/cache#docker-images) off for the job (`false`: Docker as it comes, nothing kept) or on from its start (`true`). Ubuntu 26.04. |

Each key is said once, and each thing has one way to be said. Numbers have no units: `ram=32` is 32 GB.

```yaml
runs-on: superci/cpu=16/arch=arm64/spot=false
```

A label that is not understood fails its job at once, and the job's page says what is wrong: a key no label has, a value out of its range, two things that do not go together (`arch=x64` with an arm64 family). One label for a job, not a list.

GPUs that can be named: `t4`, `l4`, `a10g`, `l40s` (AWS and Modal), and `a100`, `h100`, `h200`, `b200` (Modal).

The same keys are flags of `superci machine update`, which sets the default machine: `--cpu=8`, `--spot=false`, `--scratch=ramdisk`, `--docker-cache=false`.

## The default machine

`runs-on: superci` gives each provider's standard machine:

| Provider | Standard machine |
|---|---|
| AWS | 4 CPUs, 8 GB, 60 GB disk |
| Cloudflare | 4 CPUs, 12 GB, 20 GB disk |
| Modal | 2 CPUs, 8 GB, 64 GB disk |

On AWS the disk is the job's whole root filesystem: the image uses about 18 GB of it, so the standard machine has about 40 GB free, and `superci/cpu=8/disk=120` about 100. A private repository's runner on GitHub starts with about 14 GB free; [No space left on device in GitHub Actions](/blog/github-actions-no-space-left-on-device) has what fills a disk and how to get room.

Under **Workflows** in the dashboard you can set your own default (say, 8 CPUs on arm64). A label that says nothing else then gets that machine.

## Which Ubuntu

Unset, a Linux machine runs the Ubuntu that GitHub's `ubuntu-latest` does: 24.04 until 19 November 2026, then 26.04.

To choose, say it in the label, or under **Workflows → Default machine → Ubuntu** (`superci machine update --image=ubuntu26`):

- `superci/image=ubuntu26`: Ubuntu 26.04 with Docker 29, from now on.
- `superci/image=ubuntu24`: Ubuntu 24.04 with Docker 28, also after November.

On 26.04, `/tmp` is in memory, up to half of it, as on GitHub's own 26.04 runners. 26.04 is on AWS only for now; Cloudflare and Modal run 24.04.

## Which machine a job gets on AWS

A label says CPUs and memory. Several AWS machine types have them: for 32 CPUs and 128 GB, `m8a.8xlarge` and the older `m7a.8xlarge`, and with twice the memory `r8a.8xlarge` and `r7a.8xlarge`. A newer one runs the same job faster; which has a spot machine, and at what price, changes through the day.

SuperCI asks for a spot machine where it costs least for the speed it gives: it reads every candidate's price in every zone and starts from the lowest, counting a newer generation as a fifth faster than the one before. So a job gets the newest type when it is there and well priced, and an older or larger one when that is the better buy that hour. The job's row names the type it got, and says when AWS had no spot machine of a type asked before it.

A job that must have a certain family says so: `superci/cpu=32/family=m8a` asks for nothing else, and `superci/cpu=32/family=m8a+r8a` for either. With no spot machine of them, it goes on down your [order](/docs/order-and-limits), to an on-demand machine of the same family unless you changed that.

## The disk's speed on AWS

A machine's disk is as fast as its size deserves: 31.25 MiB a second for each CPU, up to 1,000. That is 250 on 8 CPUs, 500 on 16 and 1,000 from 32. AWS includes 125 with every disk, which is what the standard 4-CPU machine has, and sells the rest. So the speed is in each job's price: $0.007 an hour on 8 CPUs, $0.021 on 16, $0.055 from 32, a twentieth to a tenth of a spot machine's price.

It matters to a job that pulls Docker images, installs a lot, or runs a database. Measured on real machines: sixteen copies of a 300 MB database made in 14 seconds at 1,000 MiB a second where the included speed took 110, and 6 GB of images pulled in half the time at twice the speed.

- **For every job**, under **Workflows → Default machine → Disk speed**: a number gives every machine that speed (250 on the standard machine is $0.007 an hour), and **Standard** keeps what AWS includes on every size, at no extra price. In commands: `superci machine update --disk-speed=250`, `=125` for what AWS includes, or `=default` to put it back.
- **For one job**, say it in the label: `superci/cpu=8/disk-speed=1000`. From 125 to 2000.

Two kinds of job gain little from a faster disk, because each small write waits its turn: many databases at once, and test set-up that syncs every write. For those:

- **`superci/scratch=ramdisk`** keeps Docker's files, the work folder and `/tmp` in memory. Nothing is faster. What is kept there counts as memory, up to three quarters of the machine's, so ask for it on a machine with memory to spare: `superci/cpu=16/ram=64/scratch=ramdisk`. A full one says "No space left on device".
- **`superci/scratch=localdisk`** starts a machine with an NVMe disk of its own and keeps the same folders on it (a machine that has such a disk uses it whether asked or not, as when a label names a family like `family=m8id`): about ten times the small synced writes, with room for far more than memory holds. For writing a lot at once, a small machine's local disk is no faster than the standard one. Nothing on it outlives the machine.

With either, the machine's disk keeps the speed AWS includes, at no extra price: the job's writes go elsewhere. Say a speed in the label to have both: `superci/cpu=32/disk-speed=500/scratch=ramdisk`.

A job's row in the dashboard, and `superci jobs list`, say the disk it had: its size, its speed when above what AWS includes, and "RAM disk" or "local disk".

## Which provider runs it

A job goes to the first provider in your order that can run its machine. A provider that cannot (Cloudflare has no 16-CPU containers, only AWS has Windows) is passed by. If no provider you have added can run the machine, the job fails at once on GitHub, saying why, instead of waiting.

## The largest machine

A label may ask for at most 32 CPUs, and 8 GB of memory for each CPU allowed. You can raise or lower that under **Settings → Limits**. A label that asks for more is refused with a message.

## Your own labels

Your control plane answers to a list of labels. It starts with `superci` alone. Add another under **Settings → Labels**, or with `superci labels create acmeci`, and workflows can name it:

```yaml
runs-on: acmeci/cpu=8/arch=arm64
```

Every label in the list works at once, with the same keys. So you can add `acmeci`, change workflows one at a time, and remove `superci` when nothing names it any more. A job that names a removed label waits for a runner that never comes.

A label is 2 to 24 lowercase letters and digits, starting with a letter. The one added last is the one the dashboard shows in its examples.

## Your own name

**Settings → Name**, or `superci name update AcmeCI`, changes what your CI is called where people read it: the dashboard's header, the name of a GitHub App made from then on, and the message on a job that could not be run. The command stays `superci`.
