Networking Requirements for BYOC on AWS

A WarpBuild BYOC stack on AWS runs GitHub Actions jobs on EC2 instances inside your own VPC, so the network has to be right before the first runner launches: at least one public and one private subnet with internet connectivity, a security group attached to every runner instance that blocks all inbound traffic, and route tables that send internet-bound traffic through the Internet Gateway. Private subnets route outbound through NAT gateways, and every runner needs an outbound path to the WarpBuild control plane, GitHub, your package registries, and WarpBuild S3 storage for telemetry.

This page lists the prerequisites as a checklist, the outbound destinations with the failure each one produces when it is blocked, and the gateway charges that private placement adds to your own AWS bill.

Overview

Every row below comes from the AWS BYOC configuration guide, checked on 2026-08-13. Work through it before you create the stack, because three stack properties are fixed at creation time: the stack name, the S3 bucket, and the region.

Two stack modes consume that list differently. Easy create builds the VPC, the subnets, and the security group to the documented layout. Import mode takes an existing VPC, subnets, and security group as inputs, and import mode is supported on AWS only. BYOC runs on AWS, GCP, and Azure, so treat the numbers here as the AWS shape and price the other two clouds from their own published rates.

Architecture

The split is short. WarpBuild operates a control plane that watches the GitHub Actions job queue and calls the AWS API with the IAM role your connection stack created. Your account holds the VPC, the subnets, the security group, the S3 bucket, and the EC2 instances themselves. Nothing in that path opens a door into your network: the runner agent holds an outbound long poll, so the instances accept connections from nowhere, including from inside the VPC.

Four outbound destinations carry the job. Each one fails in a different place, which is what makes the failure signature useful when a route table or a security group rule is wrong.

Two traffic classes stay inside the AWS network and never reach those routes. Cache reads and writes go to the stack bucket through the S3 endpoint, which the configuration guide documents as connecting without incurring data transfer charges. Registry authentication and image pulls go through the ECR endpoints WarpBuild configures for runners in both public and private subnets. Stacks created on CloudFormation template versions before v1.4 can hit ECR authentication timeouts from public subnet runners, and the fix is a stack upgrade to v1.4 in the dashboard.

Guest coverage follows the same boundary. On AWS BYOC the supported guests are Linux and Windows Server 2022 x86-64. For WarpBuild-hosted capacity rather than your own account, US and EU are the regions WarpBuild names publicly.

Configuration

Subnet placement is a runner setting rather than a workflow setting. Enabling static IPs on a custom runner creates its instances in private subnets behind NAT gateways, and the external addresses those runners present are the addresses of the gateways, which is what an allowlist on a third-party service needs. Leave static IPs off and instances are created in public subnets with no gateway in the path.

Size the quotas per stack against a target of $CON concurrent jobs, and raise them in the region the stack lives in, since quota increases apply per region.

The workflow file carries none of this. A BYOC runner is addressed by its Runner ID, which is the runner name with the warp-custom- prefix, and a job moves between a public subnet runner set and a private subnet runner set by pointing runs-on at a different runner ID.

name: ci
on: [push]

jobs:
  unit-tests:
    runs-on: warp-custom-payments-use1-4x
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

  deploy:
    needs: unit-tests
    runs-on: warp-custom-payments-use1-4x;network.name=production-net
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh

The deploy job adds the networking addon, which joins the runner to your private network for the length of the job so a step can reach an internal database or an internal API. The addon gives the job reach into your services and leaves the outbound path alone: registration with WarpBuild and the GitHub API calls still travel the route in the table above.

Operations

Private placement adds a meter that public placement does not have. Traffic leaving a private subnet through a managed gateway carries a per-gigabyte processing charge in both directions on top of the hourly charge for the gateway itself. In US East (N. Virginia), AWS charges $0.045 per gateway-hour and $0.045 per GB processed (Amazon VPC pricing, checked on 2026-08-13). Those charges land on your own AWS bill and never appear on the WarpBuild invoice.

Per job, on an 8 minute Linux job that pulls 2 GB from destinations outside AWS:

The network line is larger than the platform fee on that profile, which is the reason to split the fleet by requirement rather than routing everything through private subnets. Jobs that need a stable outbound address get the private runner set. Everything else runs in public subnets, where inbound data transfer from the internet is $0.00 per GB (Amazon EC2 On-Demand pricing, checked on 2026-08-13). Keeping the S3 endpoint and the ECR endpoints in place holds cache traffic and image pulls off the meter entirely, and smaller images move the dominant line directly. The rule set for tightening egress once the layout is settled is on restricting outbound traffic from runners.

Three more operational habits are worth setting on day one. Put a lifecycle policy on the S3 bucket, since the artifact cache prefix and the telemetry prefix both grow without bound and 7 days is the documented recommendation. Deny intra-subnet traffic with Network ACLs, because runner instances never need to reach each other. Give every custom runner at least two instance types that are close in price and performance, so a capacity gap in one type does not park jobs in the queue.

Billing splits along the account boundary. WarpBuild charges $0.002 per runner minute for BYOC Linux and Windows runners and AWS bills your account for EC2, EBS, gateway hours, and data processing at your own rates. If the network setup is more than the workload justifies, a hosted warp-ubuntu-latest-x64-4x runs at $0.008 per minute with no VPC work at all.

One enterprise note for deploy-heavy pipelines: egress costs are handled on the enterprise tier; see zero egress on the WarpBuild enterprise tier.

Next steps depend on the open question. For the terminology behind the layout, start with VPC explained and NAT gateways explained. For the placement decision itself, can BYOC runners run in a private subnet walks the setting and its cost. For the stack, the IAM surface, and the runner configuration around this network, see the BYOC on AWS overview.

FAQ

What VPC layout does a WarpBuild AWS stack require?

At least one public and one private subnet, both with internet connectivity, with NAT gateways serving the private subnets. The documented recommendation is three public and three private subnets in different availability zones, each with at least 250 usable addresses, so instance type availability stays wide and concurrency is not capped by address exhaustion.

Which outbound destinations must the security group allow?

api.warpbuild.com for runner registration and lifecycle, github.com and api.github.com for Git operations and the Actions API, your package registries for dependency installs, and outbound HTTPS to WarpBuild S3 storage for runner telemetry. Inbound can be blocked entirely, because the runner agent polls outbound.

Do cache reads and image pulls cross the NAT gateways?

No. The stack uses an S3 endpoint for the cache and telemetry bucket, and WarpBuild configures ECR endpoints for runners in both public and private subnets, so that traffic stays inside the AWS network. Stacks on CloudFormation template versions before v1.4 can hit ECR authentication timeouts from public subnets.