Labels and machines

How the runs-on label picks a job's machine, as key=value pairs after its name: size, architecture, GPUs, Windows, the disk, a provider, or no spot 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.

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

What a label can say

KeyExampleMeaning
cpusuperci/cpu=8Eight CPUs. Memory follows: 4 GB for each CPU.
ramsuperci/cpu=8/ram=64Memory in GB.
disksuperci/disk=200Disk in GB.
disk-speedsuperci/cpu=8/disk-speed=1000The disk’s speed in MiB a second, on AWS.
disk-iopssuperci/disk-iops=6000The disk’s IOPS, on AWS.
archsuperci/arch=arm64x64 (the default) or arm64.
ossuperci/os=windowslinux (the default) or windows; macos is coming soon.
imagesuperci/image=ubuntu26Which 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).
gpusuperci/gpu=anyAny GPU, or one by name: gpu=l4.
familysuperci/cpu=32/family=m8aOnly this AWS machine family, or several: family=m8a+r8a. See below.
scratchsuperci/scratch=ramdiskWhere what a job writes most is kept: ramdisk (in memory) or localdisk (a machine with an NVMe disk of its own). AWS, Linux.
providersuperci/provider=awsOnly this provider: aws, cloudflare or modal, each of its runners in the order’s order.
spotsuperci/spot=falseNever a spot machine. See Spot machines.
docker-cachesuperci/image=ubuntu26/docker-cache=falseThe Docker image cache 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.

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:

ProviderStandard machine
AWS4 CPUs, 8 GB, 60 GB disk
Cloudflare4 CPUs, 12 GB, 20 GB disk
Modal2 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 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, 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:

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.