# Docker Builders
URL: https://www.warpbuild.com/docs/ci/docker-builders
Description: Build Docker images with WarpBuild

---
title: "Docker Builders"
excerpt: "Build Docker images with WarpBuild"
description: "Build Docker images with WarpBuild"
icon: Container
createdAt: "2025-03-03"
updatedAt: "2026-09-25"
---

WarpBuild provides powerful Docker builders that significantly accelerate your Docker build times, delivering superior performance for your containerization workflow.

<Callout type="info" title="Auto-scaling Docker builders (private beta)">
A new version of Docker builders that automatically scales out is in private beta. When there is a high concurrency of builds, extra builders that share the profile's cache are automatically spun up. It will be rolled out to everyone soon.
</Callout>

## Features

- 🚀 Fast Docker builds with WarpBuild's remote builder nodes.
- 🔄 Automatic Docker BuildX integration.
- 🔐 Secure TLS authentication.
- 🌐 Works with both WarpBuild runners and non-WarpBuild runners.
- 🔌 Integrate anywhere via API, supporting local development and various CI platforms (GitHub, GitLab, Bitbucket, Buildkite, etc.).
- 🏗️ Multi-architecture builds (amd64, arm64) out of the box.

## See it in Action

![Docker builder in action](./img/docker-builders/benchmarks.png)

Experience up to 50% faster Docker builds compared to traditional solutions. Our optimized builder infrastructure handles the heavy lifting so your CI/CD pipeline runs more efficiently.

To get started with Docker builders, go to the [Docker Builders page](https://app.warpbuild.com/ci/docker-builders) and create a builder profile.

![View docker builders](./img/docker-builders/docker-builders.png)

## Concurrency

Each builder profile corresponds to one optimized, dedicated Docker builder virtual machine with caching. Multiple jobs can run on the same builder profile in parallel and these will effectively run on the same VM in parallel.

While there is no limit on the number of builds that can be run concurrently on a builder profile, the recommended minimum resource requirements for builders is approximately 8 vCPU and 16GB memory per build job.

With auto-scaling Docker builders, currently in private beta, builds beyond one builder's capacity run on additional builder machines instead of sharing a single VM.

## Usage

### Using WarpBuild's Build Push Action (Recommended)

WarpBuild provides a drop-in replacement for the widely used `docker/build-push-action`. Our action automatically sets up the WarpBuild's Remote Docker builders for you.

> Note: We recommend that you remove the `docker/setup-buildx-action` step from your workflow if you are only using it to setup builders.

```diff
- name: Setup Buildx
- uses: docker/setup-buildx-action@v3

  name: Docker Build Push Action
- uses: docker/build-push-action@v7
+ uses: Warpbuilds/build-push-action@v7 # Uses WarpBuild Docker Builders
  with:
    context: .
    push: true
    tags: user/app:latest
+   profile-name: "super-fast-builder" # Specify the builder profile to use
```

Here's how you can use the `Warpbuilds/build-push-action` in your workflows, whether you are using WarpBuild Runners or non-WarpBuild Runners.

```yaml
jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v3

      - name: Build and push
        uses: Warpbuilds/build-push-action@v7
        with:
          context: .
          push: true
          tags: user/app:latest
          profile-name: "super-fast-builder"
          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required for WarpBuild Runners
          timeout: 600000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 10 minutes
```

### Using WarpBuild's Bake Action

WarpBuild provides a drop-in replacement for the widely used `docker/bake-action`. Our action automatically sets up the WarpBuild's Remote Docker builders for you.

> Note: We recommend that you remove the `docker/setup-buildx-action` step from your workflow if you are only using it to setup builders.

```diff
- name: Setup Buildx
- uses: docker/setup-buildx-action@v3

  name: Docker Bake Action
- uses: docker/bake-action@v7
+ uses: Warpbuilds/bake-action@v7 # Uses WarpBuild Docker Builders
  with:
    context: .
    push: true
    tags: user/app:latest
+   profile-name: "super-fast-builder" # Specify the builder profile to use
```

Here's how you can use the `Warpbuilds/bake-action` in your workflows, whether you are using WarpBuild Runners or non-WarpBuild Runners.

```yaml
jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x
    steps:
      - uses: actions/checkout@v3

      - name: Bake
        uses: Warpbuilds/bake-action@v7
        with:
          context: .
          push: true
          set: |
            *.tags=user/app:latest
          profile-name: "super-fast-builder"
          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required for WarpBuild Runners
          timeout: 600000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 10 minutes
```

### Using WarpBuild's Docker Configure Action

For users wanting more control over their workflows, WarpBuild provides a `docker-configure` action. This action sets up the builder for you in the VM and outputs all their details which you can then use in your workflow. Although, we recommend using the `Warpbuilds/build-push-action` as it is easier to use, this action allows you to use builders with your custom steps.

#### With WarpBuild Runners

```diff
 jobs:
   build:
     runs-on: warp-ubuntu-latest-x64-4x
     steps:
       - uses: actions/checkout@v4

-      - name: Setup Buildx
-      - uses: docker/setup-buildx-action@v3

+      - name: Configure WarpBuild Docker Builders
+        uses: Warpbuilds/docker-configure@v1
+        with:
+          api-key: ${{ secrets.WARPBUILD_API_KEY }} # Not required on WarpBuild Runners
+          profile-name: "super-fast-builder"
+          timeout: 300000 # The timeout(in ms) to wait for the Docker Builders to be ready. By default, it is 5 minutes

       - name: Custom Build docker image
         run: |
           ...
```

Learn more about the outputs of the `docker-configure` action in the [docker-configure action docs](https://github.com/WarpBuilds/docker-configure/tree/main?tab=readme-ov-file#outputs).

### From CLI

You can use WarpBuild's Docker builders directly from your CLI.

1. **Set your API key as an environment variable**:

   ```bash
   export WARPBUILD_API_KEY="your-api-key"
   ```

2. **Assign builders from your profile**:

   ```bash
   # Generate a unique idempotency key (16 characters) - Optional
   IDEMPOTENCY_KEY=$(uuidgen | tr -d '-' | cut -c1-16)
   BUILDER_NAME="builder-$IDEMPOTENCY_KEY"

   # Request a builder assignment
   # Note: external_unique_id is optional but recommended for idempotency
   RESPONSE=$(curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $WARPBUILD_API_KEY" \
     -d '{"profile_name": "your-profile-name", "external_unique_id": "'"$IDEMPOTENCY_KEY"'"}' \
     https://api.warpbuild.com/api/v1/builders/assign)

   # Get all builder IDs and request IDs (we'll use the first one for this example)
   BUILDER_ID=$(echo $RESPONSE | jq -r '.builder_instances[0].id')
   REQUEST_ID=$(echo $RESPONSE | jq -r '.builder_instances[0].request_id')
   ```

3. **Wait for builder to be ready and get details**:

   ```bash
   # Poll for builder details until status is ready
   echo "Waiting for builder to be ready..."
   while true; do
     DETAILS=$(curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
       https://api.warpbuild.com/api/v1/builders/$BUILDER_ID/details)
     
     STATUS=$(echo $DETAILS | jq -r '.status')
     
     if [ "$STATUS" = "ready" ]; then
       echo "Builder is ready!"
       break
     elif [ "$STATUS" = "failed" ]; then
       echo "Builder failed to initialize"
       exit 1
     fi
     
     echo "Builder status: $STATUS. Waiting..."
     sleep 2
   done

   # Extract connection information
   HOST=$(echo $DETAILS | jq -r '.metadata.host')

   # Create certificate directory
   CERT_DIR="$HOME/.docker/warpbuild/$BUILDER_NAME/$BUILDER_ID"
   mkdir -p $CERT_DIR

   # Save certificates
   echo "$DETAILS" | jq -r '.metadata.ca' > $CERT_DIR/ca.pem
   echo "$DETAILS" | jq -r '.metadata.client_cert' > $CERT_DIR/cert.pem
   echo "$DETAILS" | jq -r '.metadata.client_key' > $CERT_DIR/key.pem
   ```

4. **Create a buildx instance with your builder**:

   ```bash
   docker buildx create --name "$BUILDER_NAME" \
     --node "$BUILDER_ID" \
     --driver remote \
     --driver-opt "cacert=$CERT_DIR/ca.pem" \
     --driver-opt "cert=$CERT_DIR/cert.pem" \
     --driver-opt "key=$CERT_DIR/key.pem" \
     --use \
     tcp://$HOST
   ```

5. **Use the builder for your Docker builds**:
   ```bash
   docker buildx build --builder $BUILDER_NAME -t myimage:latest .
   ```

You can now use this builder for faster Docker builds directly from your terminal!

6. **Terminate the assigned builders after usage**:

   ```bash
   # Complete the builder session
   # To be done for all builder instances (we'll use the first one for this example)
   RESPONSE=$(curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $WARPBUILD_API_KEY" \
     -d '{"request_id": "'"$REQUEST_ID"'", "external_unique_id": "'"$IDEMPOTENCY_KEY"'"}' \
     https://api.warpbuild.com/api/v1/builder-session-requests/complete)
   
   # Remove the buildx builder configuration
   docker buildx rm $BUILDER_NAME --force
   ```

Note : User will be billed for entire duration till the assigned builders are terminated by user.

#### Resetting the cache

If you need to reset the cache for a builder profile, you can do so by using the following steps.

1. Get the builder profile id using the following command.

```bash
curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
  https://api.warpbuild.com/api/v1/builder-profiles?per_page=30&page=1
```

2. Reset the cache for the builder profile id.

```bash
curl -s -X POST \
  -H "Authorization: Bearer $WARPBUILD_API_KEY" \
  https://api.warpbuild.com/api/v1/builder-profiles/$BUILDER_PROFILE_ID/cache/reset
```

#### Working with multiple builders

If your assignment returns multiple builders, you can set up additional nodes:

```bash
# For a second builder
BUILDER_ID_2=$(echo $RESPONSE | jq -r '.builder_instances[1].id')
REQUEST_ID_2=$(echo $RESPONSE | jq -r '.builder_instances[1].request_id')

# Poll for builder details until status is ready
echo "Waiting for second builder to be ready..."
while true; do
  DETAILS_2=$(curl -s -H "Authorization: Bearer $WARPBUILD_API_KEY" \
    https://api.warpbuild.com/api/v1/builders/$BUILDER_ID_2/details)
  
  STATUS_2=$(echo $DETAILS_2 | jq -r '.status')
  
  if [ "$STATUS_2" = "ready" ]; then
    echo "Second builder is ready!"
    break
  elif [ "$STATUS_2" = "failed" ]; then
    echo "Second builder failed to initialize"
    exit 1
  fi
  
  echo "Builder status: $STATUS_2. Waiting..."
  sleep 2
done

# Extract connection information
HOST_2=$(echo $DETAILS_2 | jq -r '.metadata.host')

# Create certificate directory
CERT_DIR_2="$HOME/.docker/warpbuild/$BUILDER_NAME/$BUILDER_ID_2"
mkdir -p $CERT_DIR_2

# Save certificates
echo "$DETAILS_2" | jq -r '.metadata.ca' > $CERT_DIR_2/ca.pem
echo "$DETAILS_2" | jq -r '.metadata.client_cert' > $CERT_DIR_2/cert.pem
echo "$DETAILS_2" | jq -r '.metadata.client_key' > $CERT_DIR_2/key.pem

# Append second builder to existing buildx instance
docker buildx create --name "$BUILDER_NAME" \
  --append \
  --node "$BUILDER_ID_2" \
  --driver remote \
  --driver-opt "cacert=$CERT_DIR_2/ca.pem" \
  --driver-opt "cert=$CERT_DIR_2/cert.pem" \
  --driver-opt "key=$CERT_DIR_2/key.pem" \
  --use \
  tcp://$HOST_2
```

With multiple builders configured, your buildx instance can distribute build workloads more efficiently.

### Multi platform builds

WarpBuild supports multi-platform builds for Docker images. You can specify the platforms you want to build for using the `platforms` option in the `docker/build-push-action`.

> Note: Make sure that the builder profile being used has both architectures enabled in WarpBuild UI.

```yaml
platforms: linux/amd64,linux/arm64
```

### Deleting a Builder Profile

You can delete a builder profile from the [Docker Builders page](https://app.warpbuild.com/dashboard/runners/builder-profiles). It is necessary to wait for all the builds to finish before deleting a builder profile.

![Delete a builder profile](./img/docker-builders/builder-profiles-delete.png)

## Pricing

Docker builders are billed per **session**. A session is measured from when the builder action starts until the job completes. Multiple concurrent jobs using the same builder profile share one session, billed from the first job's start to the last job's completion.

| Size                           | Price / min | Architectures       |
| ------------------------------ | ----------- | -------------------- |
| 16vCPU, 32GB RAM, 100GB Disk   | $0.06       | amd64, arm64, multi  |
| 32vCPU, 64GB RAM, 200GB Disk   | $0.12       | amd64, arm64, multi  |
| 64vCPU, 128GB RAM, 200GB Disk  | $0.24       | amd64, arm64, multi  |
| 96vCPU, 192GB RAM, 600GB Disk  | $0.36       | amd64 only           |
| 96vCPU, 192GB RAM, 2TB Disk    | $0.52       | amd64 only           |
| 192vCPU, 384GB RAM, 600GB Disk | $0.72       | amd64 only           |
| 192vCPU, 384GB RAM, 2TB Disk   | $0.88       | amd64 only           |

> **Note:** arm64 and multi-arch builder profiles support a maximum size of 64 vCPU. The 96 vCPU and 192 vCPU sizes are only available for amd64-only profiles.

For multi-arch builds, each architecture runs on a separate builder instance, resulting in one session per architecture. However, multi-arch builders create two sessions for the same builder profile, one for each architecture. These sessions are alive until the post-action steps are complete.

**Example:** Two jobs (J1 and J2) use the same x64 builder profile with overlapping execution:
- J1: builder starts at t1, job completes at t2
- J2: builder starts at t3, job completes at t4
- Timeline: t1 < t3 < t2 < t4

→ **Billed as one session** from t1 to t4.

If both jobs use multi arch profile, you would have 2 parallel sessions for the builders one each for x64 and arm64, billed independently.

## F.A.Q.

### How does caching work for concurrent builds?

For caching behavior between concurrent builds, note that the cache is shared but `eventually consistent`. This means that layer caching from one build may not be immediately available to another concurrent build, but will be available for future builds after synchronization occurs.

### Does the builder cache/data have any TTL?

Yes, the builder cache/data has a TTL of 10 Days. If the builder profile is not used for more than 10 days, it will be reset automatically.

### Docker Builder is timing out

Docker Builders have timeout built-in so that users don't get charged for builders that are idle. We recommend that you invoke the `WarpBuilds/docker-configure` action just before the `build-and-push` action or any other step that performs docker build.

### How to use `cache-to` and `cache-from` with Docker Builders

When using Docker Builders, the `cache-to` and `cache-from` options are not required. A cached Docker Builder will automatically cache the layers and reuse them for subsequent builds.

```diff
- name: Older Docker WarpCache Backend
-  uses: docker/build-push-action@v6
-  with:
-    context: .
-    push: false
-    tags: "alpine/warpcache:latest"
-    cache-from: type=gha,url=http://127.0.0.1:49160/
-    cache-to: type=gha,url=http://127.0.0.1:49160/,mode=max

+ name: New WarpBuild Docker Builders
+  uses: Warpbuilds/docker-configure@v1
+  with:
+    profile-name: "super-fast-builder"

+ name: Build and push
+  uses: docker/build-push-action@v6
+  with:
+      context: .
+      push: false
+      tags: "alpine/warpcache:latest"
```

### Is the size of the Docker machine related to the the GitHub runner?

No, the size of the Docker machine is not limited by or related to the size of the GitHub runner used. It is determined by the size of the builder profile that you have selected.

### Do I get charged for both the GitHub runner and the WarpBuild Docker builder runtime?

Yes. These are two separate, independent resources and you will be charged for both.

### `exec format error` while building for arm64 / multi-platform builds

This is likely because the builder profile does not have the correct architectures selected for your builder profile. Ensure the builder profile has both the architectures enabled.