What Is a Remote Docker Builder?
A remote Docker builder is a dedicated build VM outside the GitHub Actions runner that keeps a layer cache on its own disk, so repeat builds reuse layers.
Last verified:
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 sends 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.
How is a remote builder different from building on the runner?
A build on the runner starts with an empty cache and loses it when the job ends, while a remote builder keeps its cache between jobs. A GitHub Actions runner is ephemeral, so the local Docker layer store is empty when the job starts and is deleted when the job ends. Every build on the runner then 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. That 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 builder that produced them, and the next build on the same profile uses them in place.
| Build on the runner | Remote Docker builder | |
|---|---|---|
| Layer cache at job start | Empty, unless imported over the network | On the builder's disk |
| Cache after the job | Deleted with the runner, unless exported | Kept on the builder |
| CPU and memory for the build | The runner's size | The builder profile's size, set independently |
| Second architecture | Usually QEMU emulation on the runner | Separate builder instance per architecture |
What is a builder profile?
A builder profile is where you configure a remote builder in WarpBuild: its size, its architectures, and its cache. You create it once in the dashboard and select it from a workflow by name with the profile-name input.
The builder size is not related to the runner size, so a small runner can drive a large builder. The runner does checkout and post-job steps while the builder does the layer work.
Several jobs on the same profile can build in parallel against the same cache. The cache is eventually consistent, so a layer from one in-flight build may not be visible to another build running at the same moment. WarpBuild Docker builders support scaling out under high concurrency. Extra builders can start when many builds run at once, they share the profile's cache, and workflows keep the same profile name.
What does using one look like in a workflow?
You replace docker/build-push-action with Warpbuilds/build-push-action and set its profile-name input to the builder profile. The setup, the GitHub-hosted runner variant, and multi-architecture builds are on Docker Builds on GitHub Actions: Remote Builders. How the builder is assigned and released during a job is on Remote Docker Builders for GitHub Actions.
How are remote builders sized and billed?
Builders are sized per profile and billed per session. Plan for roughly 8 vCPU and 16GB memory per concurrent build job on a profile. A session runs from when the builder action starts until the job completes, and concurrent jobs on one profile share one session. The runner is billed separately. Every size, its per-minute price and a worked billing example are on Remote Docker Builders: Sizes and Pricing.
For the general idea behind this, not tied to Docker or WarpBuild, see Remote Build Cache.
FAQ
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 runs cold and fills the cache again. You can also reset a profile's cache yourself through the API.
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. A multi-arch build runs each architecture on a separate builder instance. arm64 and multi-arch profiles support a maximum size of 64 vCPU.
How is a remote Docker builder billed?
Builders are billed per session at the per-minute rate of the profile size. A session runs from when the builder action starts until the job completes, and concurrent jobs on one profile share one session. The GitHub Actions runner is billed separately.
Do I need a WarpBuild runner to use a remote Docker builder?
No. Remote Docker builders work with WarpBuild runners and with other runners, including GitHub-hosted runners. On a runner that WarpBuild does not operate, pass an API key through the api-key input so the action can request a builder.
Start with $10 in free credits
Change the runner label in your workflow and keep the rest of your GitHub Actions setup. Runner time is billed per minute.