Linux runners

RunsOn supports both native x64 and arm64 Linux runners.

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
    steps:
      - uses: runs-on/action@v2
      - run: echo "Hello from x64!"

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-arm64
    steps:
      - uses: runs-on/action@v2
      - run: echo "Hello from arm64!"

runners = {
  linux-small = {
    family = ["c8i.large"]
    image  = "ubuntu24-full-x64"
  }
}

fleets = {
  linux-small = {
    runner = "linux-small"
  }
}

jobs:
  build:
    runs-on: runs-on/fleet=linux-small/env=production

Default runners#

Flex has these predefined runners. Pass one as runner=<name>, and override any part of it with other labels, for example runner=4cpu-linux-x64/family=c8. All of them use Spot instances by default (spot=false for on-demand).

Without a runner label, Flex uses 2cpu-linux-x64. To change a default runner or add your own, see custom runners.

Default images#

Opt into a specific image with the image label. When you set image, make sure your family uses instance types matching the image architecture (e.g. family=c8g+m8g for arm64).

Minimal images#

Since v3.0.7, RunsOn also publishes minimal images, for the fastest boot times. They ship the GitHub Actions runner, Docker (with Buildx and Compose), Git and Python 3, and none of the toolchains of the full images: no Node.js, Java, browsers or cloud CLIs. Use them for jobs that run in containers, or that install what they need with setup-* actions.

Like the full images, they ship libicu, which .NET needs for cultures such as en-US, and a /usr/share/dotnet that the runner user can write to, so actions/setup-dotnet works with its default install directory.

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/image=ubuntu24-minimal-x64
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci && npm test

runners = {
  linux-minimal = {
    family = ["c8i.large"]
    image  = "ubuntu24-minimal-x64"
  }
}

Minimal images are rebuilt on the same schedule as the full images, from the same repository ↗.

Examples#

Disable spot pricing for critical jobs:

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/spot=false

Only allow 4-CPU instances from compute-optimized families:

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/family=c8

Fully custom definition — launched in a private subnet with a static egress IP:

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/ram=8/family=m8+c8+r8/image=ubuntu24-full-x64/spot=false/ssh=false/private=true

Need help choosing? Use the instance finder ↗ to match AWS instances to your CPU, RAM, and architecture requirements.

Quotas#

New AWS accounts have low default quotas for standard instances, so you may need an increase to launch many jobs.

How to request an increase

1. Search for “Quotas” in the AWS console.
2. Click “Request quota increase”.
3. Select “EC2” as the service.
4. Select the standard instance type.
5. Fill in the form and submit (you request vCPUs, not instance count).
6. Repeat for both spot and on-demand quotas.