Quickstart

This quickstart takes you from nothing to a fast, cached GitHub Actions build running on your own AWS account in about 15 minutes. Three steps: install RunsOn in your AWS account, point a workflow at it, then make it fast with caching.

You’ll need an AWS account (ideally a dedicated sub-account for isolation) and a RunsOn license key — free for non-commercial use, or a 15-day trial.

Most teams start with RunsOn Flex, which gives each job precise control over its runner. Platform teams add RunsOn Fleet on top to publish a small set of standardized runner fleets. The tabs below show both — Flex is the recommended start.

1. Install RunsOn in your AWS account#

module "runs_on_fleet" {
  source  = "runs-on/runs-on/aws//modules/fleet"
  version = "v3.1.3"
  # github boundary, networking, runner fleets...
}

2. Run your first job on RunsOn#

Swap GitHub’s hosted label for a RunsOn label — that’s the only required change:

runs-on: ubuntu-latest
runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64

A complete minimal workflow:

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64
    steps:
      - uses: actions/checkout@v6
      - run: echo "Hello from RunsOn"

jobs:
  build:
    runs-on: runs-on/fleet=linux-small/env=production
    steps:
      - uses: actions/checkout@v6
      - run: echo "Hello from RunsOn Fleet"

3. Cache dependencies to run faster (recommended)#

Turn on Magic Cache by adding extras=s3-cache to your runner label, then keep using the standard actions/cache action — no other workflow changes. RunsOn transparently routes the cache to a fast, in-VPC S3 backend:

• 5x faster than the official GitHub Actions cache.
• Unlimited size (items evicted by your stack’s policy, default 10 days).
• Local to your VPC, so it’s fast, reliable, and secure.

jobs:
  build:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache
    steps:
      - uses: runs-on/action@v2
      - uses: actions/cache@v5
        with:
          path: ~/.npm
          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

runners = {
  linux-cache = {
    cpu    = 4
    ram    = 8
    family = ["c8i"]
    image  = "ubuntu24-full-x64"
    extras = ["s3-cache"]
  }
}

Learn more in the Magic Cache reference.

4. Cache Docker layers (recommended)#

The same extras=s3-cache runner also accelerates Docker builds. Point Buildx at the type=gha cache backend and RunsOn routes it to S3 transparently:

jobs:
  docker:
    runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64/extras=s3-cache
    steps:
      - uses: runs-on/action@v2
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v6
        with:
          cache-to: type=gha,mode=max
          cache-from: type=gha

Next steps#