What Is a Remote Docker Builder?

Answer

A remote Docker builder is a dedicated build virtual machine that runs docker build outside the GitHub Actions runner and keeps a layer cache on its own disk between jobs. The runner checks out the repository and issues the build over a TLS connection, the builder does the work, and a repeat build reuses the layers already on that disk instead of rebuilding them.

The problem it addresses comes from the runner lifecycle. A GitHub Actions runner is ephemeral, so the local Docker layer store is empty when the job starts and is discarded when the job ends. Every build therefore reinstalls the same base packages and recompiles the same unchanged stages. The usual workaround exports the layer cache to a registry or to the Actions cache at the end of a build and imports it at the start of the next one, which trades rebuild time for upload and download time over the network.

A remote builder removes both the rebuild and the transfer. The layers stay on a disk attached to the machine that produced them, and the next build attaches to the same machine. Rates for every builder size are on the pricing page.

Three facts define the model, and the rest of this page is the detail behind them.

• One builder profile is one builder virtual machine. The profile carries the size, the disk, the architectures, and the cache. You create it once in the dashboard and reference it from a workflow by name.
• Several jobs on the same profile build in parallel against the same cache. There is no limit on concurrent builds per profile, and the cache is shared between them, with layers from one in-flight build becoming available to the others after synchronization.
• A session is the billing unit. A session runs from when the builder action starts until the job completes, and concurrent jobs on one profile share a single session billed from the first job start to the last job completion.

The builder is independent of the runner it serves, so it also works from runners WarpBuild does not operate and from a local terminal through the API. The Docker builders documentation is the reference for the behavior described below.

Detail

The profile is the unit of configuration

Everything about a builder lives on the profile: the size in vCPU and memory, the disk, the enabled architectures, and the layer cache that accumulates on that disk. A workflow selects a profile by passing profile-name to the WarpBuild action, and nothing else in the job changes.

Two consequences follow from that. First, the builder size is decoupled from the runner size, so a 4 vCPU runner can drive a 192 vCPU builder. The runner is doing checkout, orchestration, and post-job steps while the builder does the compilation and layer work. Second, the cache is scoped to the profile rather than to a branch or a workflow, so every job pointing at api-builder shares one layer store. Splitting unrelated images across separate profiles keeps one team's churn from evicting another team's layers.

Sizing and the recommended 8 vCPU per build job

The documented recommendation is roughly 8 vCPU and 16GB memory per concurrent build job. There is no enforced concurrency limit, so this is a sizing guide rather than a quota. The table below takes the published profile sizes and rates and applies that recommendation to get a concurrency target for each one. Rates come from the Docker builders documentation and the pricing page, checked on 2026-08-13.

arm64 and multi-arch profiles cap at 64 vCPU, so the three largest rows are available for amd64-only profiles. Disk is the other axis worth reading carefully: a layer cache that holds several large base images and many build stages grows into that disk, and the 2TB variants exist for repositories whose image set outgrows 600GB.

Sessions, and why overlap matters to the bill

Session billing is the part that surprises people, so it is worth walking through the documented example. Two jobs share one x64 profile. J1 starts its builder at t1 and completes at t2. J2 starts at t3 and completes at t4. The order is t1 < t3 < t2 < t4, so the two jobs overlap. That is billed as one session from t1 to t4 rather than as two sessions.

The practical reading: builds that overlap on one profile are cheap to add, and builds spread thinly across the day each carry their own session. A matrix of six images that all fire on a merge is one stretch of builder time. The same six images built one at a time across an afternoon is six stretches.

Here is that arithmetic on a full month. The assumptions are stated so you can substitute your own measurements.

• 500 image builds per month, each on a warp-ubuntu-latest-x64-4x runner at $0.008 per minute.
• Each runner job runs 6 minutes end to end, including checkout, the build step, and post-job steps.
• One builder profile at 32 vCPU, 64GB, 200GB disk, $0.12 per minute, sized for the 4 concurrent jobs above.
• Overlapped case: builds arrive as 125 fan-outs of 4 jobs, and each fan-out holds the builder for an 8 minute session.
• Staggered case: the same 500 builds arrive one at a time, and each holds the builder for a 5 minute session.

Same 500 builds, same profile, $180.00 of difference from scheduling alone. Batching image builds into the same window is the single largest lever on a builder bill.

Only the runner line has a GitHub-hosted equivalent, because GitHub-hosted runners have no remote builder product to price against. On that line, warp-ubuntu-latest-x64-4x at 4 vCPU and 16GB lists at $0.008 per minute where the 4-core GitHub-hosted Linux larger runner at 4 vCPU and 16GB lists at $0.012 per minute, a 33 percent lower list price, so the same 3,000 minutes would be $36.00. GitHub publishes those rates in the GitHub Actions minute multipliers reference, checked on 2026-08-13.

The minimal configuration

Create a builder profile in the dashboard, then swap the build action. The WarpBuild action is a drop-in replacement for docker/build-push-action, and the docker/setup-buildx-action step comes out when its only purpose was setting up a builder.

name: build-image
on:
  push:
    branches: [main]
  pull_request:

jobs:
  image:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v5

      - name: Build and push
        uses: Warpbuilds/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/acme/api:${{ github.sha }}
          profile-name: "api-builder"
          timeout: 600000

timeout is the wait in milliseconds for the builder to become ready and defaults to 10 minutes. On a runner WarpBuild does not operate, add api-key: ${{ secrets.WARPBUILD_API_KEY }} so the action can request a builder assignment. Teams that use Bake swap docker/bake-action for Warpbuilds/bake-action with the same profile-name input, and teams that need custom build steps use Warpbuilds/docker-configure@v1, which sets up the builder and outputs its connection details for later steps.

One line usually comes out at the same time. With a remote builder, cache-to and cache-from are not required, because the builder holds the layers on its own disk and reuses them for later builds. Leaving a registry or Actions cache export in place means paying to move layers that the builder already has. The caching documentation covers the separate WarpBuild cache for dependency directories and build artifacts, which is a different mechanism and stays useful alongside a builder.

For multi-architecture images, enable both architectures on the profile and pass the platforms:

      - name: Build and push multi-arch
        uses: Warpbuilds/build-push-action@v6
        with:
          context: .
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ghcr.io/acme/api:${{ github.sha }}
          profile-name: "api-builder-multi"

Each architecture runs on its own builder instance, so a multi-arch build opens two sessions on the profile, one per architecture, and both are billed independently until the post-action steps finish. A profile missing an architecture that a build requests produces an exec format error, which is the first thing to check when an arm64 build fails on a profile that was previously amd64 only.

Cache lifetime and resets

The builder cache has a TTL of 10 days. A profile that goes unused for longer than that is reset automatically, and the next build repopulates it. Daily use keeps a profile warm indefinitely.

Manual resets exist for the case where the cache holds something wrong, such as layers built from a base image that was later republished under the same tag. Fetch the profile ID from GET /api/v1/builder-profiles, then post to /api/v1/builder-profiles/{id}/cache/reset. The next build runs cold.

One more behavior belongs here. The cache shared between concurrent builds is eventually consistent, so a layer produced by one in-flight build may not be visible to another build running at the same moment, and it becomes available to later builds after synchronization. Two jobs starting simultaneously on a cold profile can therefore each build the same base stage once. Warming a profile with a single build before a wide fan-out avoids that duplicate work.

Where the runner still matters

The builder does the image work, and the runner still does checkout, test steps, and anything else in the job. Both are billed, on two separate lines, because they are two separate resources. A job that spends 2 minutes on checkout and tests and 4 minutes waiting on the builder is paying runner rate for all 6 minutes and builder rate for the overlapping stretch.

That makes the runner size a real choice rather than a formality. Undersizing the runner slows checkout and post-job steps that the builder cannot help with, and oversizing it pays a higher per-minute rate for time spent waiting on the builder. The remote Docker builder catalog lists every profile size with its rate, and the setup guide walks through the migration from a registry-backed cache.

Related Questions

How long does the layer cache on a remote Docker builder last?

The builder cache has a TTL of 10 days. A builder profile that goes unused for more than 10 days is reset automatically, and the next build after that reset runs cold and repopulates the cache on the profile disk. A profile that gets used daily keeps its layers, and you can force a reset yourself through the builder profile cache reset API. The Docker builders documentation carries the reset endpoints.

Which architectures can one builder profile build?

A profile can be amd64, arm64, or multi-arch, and the architectures have to be enabled on the profile before a build requests them. arm64 and multi-arch profiles cap at 64 vCPU, so the 96 vCPU and 192 vCPU sizes are amd64 only. A multi-arch build runs each architecture on a separate builder instance, which produces one session per architecture, billed independently. The builder catalog shows which sizes carry which architectures.

What does a remote Docker builder cost?

Builders are billed per session at the rate of the profile size, from $0.06 per minute for 16 vCPU with 32GB and a 100GB disk up to $0.88 per minute for 192 vCPU with 384GB and a 2TB disk. The GitHub Actions runner is billed separately at its own per-minute rate. Every rate is on the pricing page.

Do I need a WarpBuild runner to use a remote Docker builder?

No. Remote Docker builders work with WarpBuild runners and with runners WarpBuild does not operate, including GitHub-hosted runners and local machines. On a runner WarpBuild does not operate, pass an API key through the api-key input so the action can request a builder assignment. The same API drives builders from a terminal or another platform, and Docker builds on GitHub Actions covers the workflow patterns. For the vendor-neutral definition of the underlying idea, see remote build cache.