# RunsOn > RunsOn runs ephemeral self-hosted GitHub Actions runners in your own AWS account: one CloudFormation or Terraform stack, no Kubernetes, any EC2 instance type per job. You pay AWS for compute and RunsOn a flat annual license. RunsOn has two modes. Flex lets each workflow choose its runner in the `runs-on:` label. Fleet lets a platform team publish Terraform-managed runner fleets that workflows target by name. Moving a job to RunsOn Flex only requires changing its label: ```yaml runs-on: runs-on=${{ github.run_id }}/runner=2cpu-linux-x64 ``` Fleet jobs target a published fleet with `runs-on/fleet=/env=`. [Job labels](https://runs-on.com/docs/runners/labels/) lists every Flex label option. Every page below is also served as markdown: request it with `Accept: text/markdown`. ## Getting started - [Documentation](https://runs-on.com/docs/): Everything RunsOn provides for teams running GitHub Actions on AWS, including compute, caching, observability, and security. - [Quickstart](https://runs-on.com/quickstart/): From zero to a cached, 10x-cheaper GitHub Actions build running in your own AWS account. - [Flex vs Fleet](https://runs-on.com/docs/flex-vs-fleet/): Choose the right RunsOn mode for your GitHub Actions runners on AWS. - [Flex installation guide](https://runs-on.com/installation/flex/): RunsOn is the best way to run GitHub Actions in your own AWS infrastructure, and get 10x cheaper runners. - [Fleet installation guide](https://runs-on.com/installation/fleet/): Deploy RunsOn Fleet on AWS with Terraform or OpenTofu. - [GitHub Enterprise Server and GHE.com](https://runs-on.com/installation/github-enterprise/): Run RunsOn Flex or Fleet with GitHub Enterprise Server or GHE.com. The URL to set, actions on GHES, networking, and what differs from github.com. ## Runners Runner types available across RunsOn Flex and Fleet - Linux, Windows, GPU - plus the capabilities you can layer on top. - [Runner types and capabilities](https://runs-on.com/docs/runners/): Overview of the different runner types available in RunsOn - Linux, Windows, GPU - plus the capabilities you can layer on top. - [Job labels](https://runs-on.com/docs/runners/labels/): Configure RunsOn runners with per-job runs-on labels and reusable runner definitions — CPU, GPU, RAM, instance type, volume size, sticky cache disks, and more. - [Runner platforms - Linux, Windows, GPU](https://runs-on.com/docs/runners/platforms/): Self-host GitHub Actions runners on AWS across Linux (x64 + arm64), Windows, and GPU — for any GitHub plan. macOS is not yet supported. - [Linux runners](https://runs-on.com/docs/runners/platforms/linux/): Native x64 and arm64 Linux runners on any EC2 instance, from Flex labels or Fleet runner definitions. - [Windows runners](https://runs-on.com/docs/runners/platforms/windows/): Windows Server runners on EC2, from Flex labels or Fleet runner definitions. - [GPU runners](https://runs-on.com/docs/runners/platforms/gpu/): NVIDIA and AMD GPU runners on EC2 for ML and graphics workloads, from Flex labels or Fleet runner definitions. - [macOS runners](https://runs-on.com/docs/runners/platforms/macos/): Why RunsOn doesn't offer macOS runners yet: Apple's 24-hour minimum on EC2 Mac instances. - [Runner environment - paths and environment variables](https://runs-on.com/docs/runners/environment/): Where RunsOn runners keep the job workspace, tool cache, and RunsOn files, and which environment variables every job receives. - [Runner capabilities](https://runs-on.com/docs/runners/capabilities/): Compare optional RunsOn runner capabilities across Linux, Windows, Flex, and Fleet. - [Static egress IPs](https://runs-on.com/docs/runners/capabilities/static-ips/): Static egress IPs for RunsOn Flex and Fleet runners through private subnets, NAT gateways, and Elastic IPs. - [Local storage (NVMe)](https://runs-on.com/docs/runners/capabilities/local-storage-nvme/): Use local NVMe on EC2 instance-store types for build workspaces, temporary files, and Docker layers on Linux and Windows. - [Using tmpfs for faster builds](https://runs-on.com/docs/runners/capabilities/yolo-mode/): How to use the tmpfs feature with RunsOn, for faster builds - [Sharing files across workflow jobs with EFS](https://runs-on.com/docs/runners/capabilities/shared-volumes/): How to use the EFS file system with RunsOn, for storing files across GitHub Actions workflow jobs - [Sticky disks (EBS)](https://runs-on.com/docs/runners/capabilities/sticky-disks/): Keep build caches on a persistent EBS disk and restore them at native filesystem speed on Flex and Fleet. - [CodeQL code scanning](https://runs-on.com/docs/runners/capabilities/code-scanning/): Run GitHub CodeQL code scanning on RunsOn Fleet or Flex self-hosted runners, with default setup or advanced setup. - [Dependabot](https://runs-on.com/docs/runners/capabilities/dependabot/): Run Dependabot update jobs on RunsOn Flex or Fleet self-hosted runners. - [Docker Hub pull-through cache](https://runs-on.com/docs/runners/capabilities/pull-through-registry/): Mirror Docker Hub and other public registries through ECR in your own account, so runners pull images over the VPC and never hit 429 rate limits. - [Local OpenTelemetry collector](https://runs-on.com/docs/runners/capabilities/local-otel-collector/): Send workflow traces, logs, and metrics to the local OTLP endpoint on RunsOn runners. RunsOn captures them and forwards them to your backend. - [Nested virtualization](https://runs-on.com/docs/runners/capabilities/nested-virtualization/): When to use Linux KVM or Windows Hyper-V inside RunsOn runners, and the EC2 constraints that matter. - [Remote access (SSM and SSH)](https://runs-on.com/docs/runners/capabilities/remote-access/): Use SSM and optional SSH access to troubleshoot RunsOn Flex and Fleet runner instances. - [Amazon Bedrock and GitHub Copilot coding agent](https://runs-on.com/docs/runners/capabilities/ai-agents/): Run AI-assisted CI on RunsOn runners — IAM access to invoke Amazon Bedrock models, and self-hosted execution for GitHub's Copilot coding agent. - [Custom runners & images](https://runs-on.com/docs/runners/custom/): Define custom runner shapes and custom AMIs for RunsOn — per job in Flex (.github/runs-on.yml) or in the Terraform catalog for Fleet. - [Building a custom AMI with Packer](https://runs-on.com/docs/runners/custom/building-ami/): Learn how to build a custom AMI using Packer to prepopulate with your software, ensure compliance, and control over your GitHub Actions workflows. ## Speed and cost Faster jobs and smaller bills: Magic Cache, warm pools, rightsizing, spot instances, cost control and licensing. - [Magic Cache](https://runs-on.com/docs/performance/caching/): Magic Cache swaps the GitHub Actions cache backend for a fast, unlimited S3 cache in your own VPC. Same actions/cache config, nothing leaves your account. - [Magic Cache for GitHub Actions](https://runs-on.com/docs/performance/caching/actions/): How to enable RunsOn Magic Cache for actions/cache and language setup actions — unlimited, S3-backed caching with no per-step changes. - [Caching for Docker builds](https://runs-on.com/docs/performance/caching/docker/): Cache Docker layers on RunsOn runners with the Magic Cache (type=gha), the S3 BuildKit backend (type=s3), or the ephemeral ECR registry (type=registry). - [Rightsizing runners](https://runs-on.com/docs/performance/rightsizing/): Choose the right instance family, CPU, RAM, and disk for RunsOn runners — fast enough to cut wall-clock time without overpaying for idle capacity. - [Warm pools](https://runs-on.com/docs/performance/warm-pools/): Learn how to use runner warm pools to get <10s queuing time for your GitHub Actions workflows on self-hosted runners. - [Spot instances and interruptions](https://runs-on.com/docs/costs/spot-pricing/): How RunsOn launches runners on EC2 Spot capacity, and when to opt out. - [Cost control](https://runs-on.com/docs/costs/cost-control/): Reduce RunsOn spend with spot tuning and right-sizing, then keep it in check with budgets, scheduled cost reports, tags, and automatic termination safeguards. - [Licensing and usage](https://runs-on.com/docs/costs/licensing/): How the shared RunsOn license works across Flex and Fleet, and how usage is measured. ## Operate Run the RunsOn stack day to day: environments, networking, security, scale, retries, and observability. - [Security: what runs in your account, and what RunsOn receives](https://runs-on.com/docs/control-plane/security/): Where your code runs, what RunsOn receives, how jobs are kept apart, what the GitHub App can do, and which settings to change. - [Runtime security with StepSecurity Harden-Runner](https://runs-on.com/docs/integrations/stepsecurity/): Monitor and restrict what a job does on a RunsOn runner with StepSecurity Harden-Runner: network egress, GitHub API calls and file changes. Flex and Fleet. - [Vulnerability disclosure](https://runs-on.com/docs/control-plane/vulnerability-disclosure/): How to report a security vulnerability in RunsOn, what to include, the rules for testing, and the safe harbor for good-faith research. - [Environments and stack isolation](https://runs-on.com/docs/control-plane/environments/): Use RunsOn environments to isolate stacks, runtime permissions, GitHub App boundaries, networks, and regions. - [Networking](https://runs-on.com/docs/control-plane/networking/): Shared networking model for RunsOn Flex and Fleet: VPCs, public and private runners, static egress, SSH, SSM, WAF, and ingress differences. - [Rate limits and scale](https://runs-on.com/docs/control-plane/rate-limits/): How RunsOn paces AWS and GitHub API calls to protect shared quotas at high volume, what you can tune, and the AWS quotas you must raise yourself. - [Job retries and housekeeping](https://runs-on.com/docs/control-plane/housekeeping/): Jobs processed with RunsOn are regularly inspected to ensure they were able to get a runner assigned, as well as detect idle runners and remove them. - [Observability](https://runs-on.com/docs/observability/): Per-job metrics, runner metadata, OpenTelemetry, CloudWatch dashboards, and cost signals for Flex and Fleet. - [OpenTelemetry](https://runs-on.com/docs/observability/opentelemetry/): Per-job runner metrics in the GitHub Actions UI, plus the exact OTLP signal behavior RunsOn exports server- and runner-side. - [CloudWatch](https://runs-on.com/docs/observability/cloudwatch/): AWS-native observability for RunsOn — Flex and Fleet control-plane dashboards, plus per-job CloudWatch metrics via runs-on/action@v2. - [Email and Slack alerts](https://runs-on.com/docs/observability/alerts/): When RunsOn pages you by email or Slack — and why most errors no longer do - [SigNoz dashboards](https://runs-on.com/docs/observability/signoz/): Import the RunsOn Operations, Runners, and Troubleshooting dashboards into SigNoz. - [Logfire](https://runs-on.com/docs/observability/logfire/): Send RunsOn job, capacity, cost, and runner telemetry to Pydantic Logfire, then install the RunsOn dashboards and alerts. ## Maintain Upgrade the stack, look up configuration, diagnose issues, and uninstall cleanly. - [Configuration layers](https://runs-on.com/docs/maintenance/configuration/): How RunsOn is configured — per-job labels and repo/stack files in Flex, Terraform-owned runner catalogs in Fleet. - [Flex configuration](https://runs-on.com/docs/maintenance/configuration/flex/): Reference for every RunsOn Flex setting, as CloudFormation stack parameters or Terraform / OpenTofu module inputs. - [Fleet configuration](https://runs-on.com/docs/maintenance/configuration/fleet/): Complete reference for configuring RunsOn Fleet — every input of the Terraform module. - [Upgrades](https://runs-on.com/docs/maintenance/upgrades/): Upgrade RunsOn while preserving configuration — CloudFormation stack updates for Flex, Terraform module upgrades for Fleet, plus how to downgrade. - [Upgrade to v3.2](https://runs-on.com/docs/maintenance/v3-2-upgrade/): Upgrade safely to RunsOn v3.2: required Terraform changes, CloudFormation checks, cache isolation, and Fleet rollout steps. - [Migrate from v2 to v3](https://runs-on.com/docs/maintenance/v3-migration/): Breaking changes, replacements, and rollout guidance for upgrading an existing RunsOn v2 installation to v3. - [Troubleshooting](https://runs-on.com/docs/maintenance/troubleshooting/): Diagnose RunsOn runner and stack issues across Flex and Fleet: webhook delivery, EC2 launch failures, scale-set routing, runner groups, and logs. - [roc CLI](https://runs-on.com/docs/maintenance/troubleshooting/cli/): Command line tool to manage and troubleshoot your RunsOn installation - [Uninstall](https://runs-on.com/docs/maintenance/uninstall/): Learn how to uninstall RunsOn. ## Learn Tips, best practices, and deep dives into GitHub Actions. - [Accelerated Go CI for GitHub Actions](https://runs-on.com/docs/guides/languages/go/): Speed up Go builds with massive CPU runners and unlimited S3-backed caching on RunsOn. - [Ruby & Rails CI best practices](https://runs-on.com/docs/guides/languages/ruby/): Speed up your Ruby and Rails CI workflows with RunsOn: vertical scaling, memory optimization, caching strategies, and performance tuning. - [Accelerated Rust CI for GitHub Actions](https://runs-on.com/docs/guides/languages/rust/): Speed up Rust builds by up to 2x while cutting costs by 90%, using RunsOn's optimized runners and Magic Cache. With real-world benchmarks. - [Tips](https://runs-on.com/tips/): Community tips and tricks for using RunsOn ## Evaluate RunsOn - [Pricing](https://runs-on.com/pricing/): A flat annual license per legal entity, priced by monthly runner volume tier, with no per-minute or per-seat fees. Compute is billed by AWS at spot prices. 15-day free trial. - [Cost calculator](https://runs-on.com/calculator/): Monthly cost of GitHub Actions minutes on GitHub-hosted runners compared with RunsOn on AWS, for Linux x64, arm64, Windows and GPU. - [GitHub Actions runner benchmarks](https://runs-on.com/benchmarks/): CPU speed, cache throughput, disk I/O and EC2 instance benchmarks across GitHub Actions runner providers. - [Customer stories](https://runs-on.com/success-stories/): Teams that moved their GitHub Actions to RunsOn, with their own numbers: CI cost before and after, build times, and how they switched. - [Fastest AWS EC2 Instances (CPU Benchmark)](https://runs-on.com/benchmarks/aws-ec2-instances/): Single-thread and multi-core CPU scores of AWS EC2 instance types at 2 vCPU, with spot and on-demand prices and interruption rates, to pick CI runners. - [Self-hosted GitHub Actions runners](https://runs-on.com/github-actions-self-hosted-runners/): Self-hosted runners in your own AWS account without maintaining them, with costs compared to GitHub-hosted runners and to running ARC or EC2 scripts yourself. - [Runners for GitHub Enterprise Server and GHE.com](https://runs-on.com/github-enterprise-runners/): RunsOn on GitHub Enterprise Server and GHE.com (data residency): runners in your own AWS account and region, Flex or Fleet across an enterprise, and what admins need ready. - [Alternatives to GitHub-hosted runners](https://runs-on.com/alternatives-to/github-actions-runners/): RunsOn compared with BuildJet, WarpBuild, Depot and Namespace. - [Actions Runner Controller (ARC) alternative](https://runs-on.com/alternatives-to/actions-runner-controller/): Ephemeral EC2 runners from one CloudFormation stack instead of runners on Kubernetes. ## Optional - [Changelog](https://runs-on.com/changelog/): Release notes for every RunsOn version. - [GitHub Actions workflows, from basic to complex](https://runs-on.com/github-actions/): A hands-on GitHub Actions series that builds workflows up from a minimal example to advanced CI/CD pipelines, one concept at a time. - [Run your GitHub Actions jobs in the AWS region you choose](https://runs-on.com/blog/github-actions-runners-in-your-aws-region/): RunsOn runs your CI in your AWS account, in the region you deploy it to. Last week, 24.4 million jobs ran across 16 AWS regions. Here is the map. - [Send RunsOn telemetry to Pydantic Logfire](https://runs-on.com/blog/runs-on-pydantic-logfire/): Logfire now has a RunsOn integration: point your stack at it and get dashboards for jobs, queue times, Spot interruptions, cost, and runner usage. - [Disks? Where we're going, we don't need disks](https://runs-on.com/blog/tmpfs-github-actions-runners/): With extras=tmpfs, a RunsOn runner keeps its workspace and Docker's data in RAM. PostHog's image build: 9m05s to 5m02s, for 13 times less than on GitHub. - [AWS CodeBuild runners for GitHub Actions vs RunsOn: same AWS, older machines](https://runs-on.com/blog/aws-codebuild-github-actions-runners-vs-runson/): A cold Rust build costs $0.050 and takes 4m42s on CodeBuild's 4 vCPU size; RunsOn does it for $0.0079 in 1m53s. Setup, speed and cost, measured. - [Trace GitHub Actions jobs with OpenTelemetry and RunsOn](https://runs-on.com/blog/github-actions-opentelemetry-tracing/): Trace a GitHub Actions job from webhook to test with RunsOn and otel-cli. In our demo, a 15-second test step ran 0.3 seconds of tests. - [From 24 minutes to 10: faster FreeCAD builds on Linux and Windows](https://runs-on.com/blog/freecad-faster-builds-with-fleet-pools/): Faster runners halved FreeCAD's Linux and Windows CI time. Preparing the Windows dependencies in Fleet pools took off the wait before every build. - [How we test RunsOn on real repos](https://runs-on.com/blog/how-we-benchmark-real-repos/): The rules behind our repo tests: what we change, which GitHub runner we compare against, the two clocks we read, and what goes into cost per run. - [RunsOn pays for itself at 22 jobs a day](https://runs-on.com/blog/runson-break-even/): What a RunsOn stack costs before it runs a single job, for Flex and Fleet, and the job volume where it beats GitHub-hosted runners. - [RunsOn handled 3.21 million GitHub Actions jobs in a single day](https://runs-on.com/blog/3210k-jobs-per-day/): RunsOn crossed three million daily GitHub Actions jobs, reaching a new peak of 3.21 million. That is 12% above the previous record of 2.87 million. - [Making Rust build faster on runs-on](https://runs-on.com/blog/making-rust-build-faster/): We compared a Rust project's CI performacnce on matched 2-CPU and 4-CPU GitHub and runs-on runners, with and without caching. - [RunsOn handled 2.87 million GitHub Actions jobs in a single day](https://runs-on.com/blog/2870k-jobs-per-day/): RunsOn reached a new daily peak of 2.87 million GitHub Actions jobs, up 35% from the previous record of 2.13 million. - [Taking Omarchy's nightly ISO build from 13 minutes to under 5](https://runs-on.com/blog/speeding-up-omarchy-nightly-build/): Two workflow changes cut Omarchy’s nightly ISO build to 4m43s: a faster runs-on runner and skipping compression on an already compressed artifact. - [RunsOn v2 is being deprecated](https://runs-on.com/blog/runson-v2-deprecation/): RunsOn v2 will reach end of life on September 15, 2026, instead of July 31. RunsOn v3 is stable and the migration guide is ready. - [Sticky disks: native-speed GitHub Actions caches on EBS](https://runs-on.com/blog/introducing-sticky-disks/): RunsOn v3.2 adds persistent EBS-backed caches that stay in their native format, so CI no longer spends its time packing and unpacking archives. - [What's new in RunsOn v3.2](https://runs-on.com/blog/whats-new-in-runson-v3-2/): RunsOn v3.2 adds persistent EBS caches, cost-aware operations dashboards, safer Fleet Spot recovery, and a clearer upgrade path for cache isolation. - [RunsOn handled 2.13 million GitHub Actions jobs in a single day](https://runs-on.com/blog/2130k-jobs-per-day/): RunsOn crossed two million daily GitHub Actions jobs for the first time, setting a new record at 2.13 million jobs in one day. - [M9g ARM64 runners: ~30% faster single-thread than Graviton4 or GitHub's runners](https://runs-on.com/blog/m9g-arm64-runners/): RunsOn can now launch GitHub Actions ARM64 runners on Graviton5-based M9g instances: ~27% faster single-thread than m8g, ~31% faster than GitHub's ARM64. - [Tier-based pricing for Flex and Fleet](https://runs-on.com/blog/tier-based-pricing-for-flex-and-fleet/): One license now covers both RunsOn products, priced on monthly runner volume across four tiers. Existing subscriptions stay on their current plan. - [Introducing RunsOn Fleet: a scale-set mode for GitHub Actions runners](https://runs-on.com/blog/introducing-runson-fleet/): A new scale-set mode for GitHub Actions runners on AWS. Built for platform teams that want a reviewed, fixed catalog instead of per-job labels. - [RunsOn handled 1.64 million GitHub Actions jobs in a single day](https://runs-on.com/blog/1640k-jobs-per-day/): RunsOn reached a new milestone with 1.64 million GitHub Actions jobs handled in a single day.