Quickstart

Flex installs as a single CloudFormation stack, in about 10 minutes.

a. Launch the stack. Click your region. AWS opens the CloudFormation quick-create screen with the RunsOn template already loaded.

b. Fill in three fields and create the stack. Under Main configuration, enter your GitHub organization name, your license key, and an email for cost reports and alerts. Tick the acknowledgment boxes at the bottom, click Next, then Submit on the review screen. The stack reaches CREATE_COMPLETE after about 10 minutes. AWS also emails you an alert subscription request: confirm it.

c. Register the GitHub App. Open the stack’s Outputs tab, click the RunsOnEntryPoint URL, then Register GitHub App. Pick the repositories RunsOn should run jobs for. This creates a private GitHub App whose credentials live only in your AWS account. Stay logged in to GitHub during this step. GitHub then sends you back to the RunsOn status page: every check should be under Passing.

Want screenshots of every screen? Follow the Flex install guide. Need Terraform / OpenTofu, an existing VPC, or IAM permission boundaries? Install Flex with the Terraform module instead; every input is in the Flex Terraform reference.

Fleet installs with the official Terraform / OpenTofu module. On top of the list above, you need Terraform or OpenTofu, and a VPC with at least one public subnet.

a. Create the GitHub App. Enter your organization name, then click Create App. GitHub opens its app form with the name and permissions already filled in.

Once the app exists, note its App ID, generate a private key (GitHub downloads a .pem file), and click Install App to install it on your organization.

b. Add the module and apply. Paste this into your Terraform configuration and fill in your license key, alert email, App ID, private key file, and network:

module "runs_on_fleet" {
  source  = "runs-on/runs-on/aws//modules/fleet"
  version = "v3.5.0"

  stack_name  = "runs-on-fleet"
  license_key = "your-license-key"
  email       = "alerts@example.com"

  github_app_id          = 123456
  github_app_private_key = file("runs-on-fleet.private-key.pem")

  vpc_id            = "vpc-0123456789abcdef0"
  public_subnet_ids = ["subnet-0123456789abcdef0"]

  # Same shape as the Flex 2cpu-linux-x64 runner: 2 vCPUs, like GitHub's
  # standard Linux runner.
  runners = {
    small-x64 = {
      cpu    = 2
      family = ["m8", "r8"]
      image  = "ubuntu24-full-x64"
    }
  }

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

Run terraform init and terraform apply (or the tofu equivalents), then confirm the alert subscription email AWS sends you. This publishes one fleet, linux-small, in the production environment. It registers into your organization’s Default runner group; set runner_group on a fleet to use another group, which you create first since Fleet never creates one.

Running Fleet across a GitHub Enterprise, or on private subnets? The Fleet install guide covers enterprise mode, runner groups, and private networking. Every input is in the Fleet configuration reference.

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

The label is composable — request exactly the machine you want, for example cpu=4/ram=16/family=m8a+m8i or runner=16cpu-linux-arm64. See all job labels and Linux runners.

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

Workflows target a fleet by name and environment: runs-on/fleet=<fleet>/env=<environment>. The platform team decides which fleets exist; workflow authors only pick one.

On Fleet, Magic Cache is a runner setting. Add extras = ["s3-cache"] to the runner from step 1 and re-apply; every fleet that uses it gets the cache, and workflows keep using actions/cache with the same runs-on/fleet=linux-small/env=production label.

runners = {
  small-x64 = {
    cpu    = 2
    family = ["m8", "r8"]
    image  = "ubuntu24-full-x64"
    extras = ["s3-cache"]
  }
}