How Do I Reset a Docker Builder Cache?

Reset the cache on the builder profile: one POST to the WarpBuild API clears the persistent layer cache held on that profile's builder VM and leaves the profile itself in place, so the profile name, size, and architectures stay as they were and no workflow file changes. The next build on that profile starts cold and rebuilds its layers, which is why a reset is worth timing rather than reaching for it at the first cache miss.

Answer

A builder profile corresponds to one dedicated Docker builder virtual machine with caching attached, per the Docker builders documentation. The layers live on that machine's local disk and are addressed by profile name, so there is no cache key or tag to bump and nothing in the Dockerfile that clears them. Clearing happens through the API instead.

Two calls do it. The first lists your builder profiles so you can read the profile id; the second resets that profile's cache:

export WARPBUILD_API_KEY="wkey-xxxx"

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

BUILDER_PROFILE_ID="wxxxxxxxxxxxxxxx"

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

The key comes from the API keys page with the ci and cache scopes granted, as described in the automation documentation. The same key drives the rest of the builder flow, so a scheduled reset is a few lines in an existing maintenance workflow. Docker builds on GitHub Actions covers the whole builder configuration; this page covers the reset.

Detail

The request shape

Both calls carry Authorization: Bearer $WARPBUILD_API_KEY against the https://api.warpbuild.com host. The reset takes no JSON body at all: the profile id in the path is the entire input, which makes it safe to wire into a chat command or a scheduled job without templating a payload.

Three things the reset leaves alone are worth stating, because they decide whether you need a change window. The profile survives, so profile-name in every workflow still resolves. Deleting a profile is the separate operation, done from the Docker Builders page, and the documentation requires all builds to finish before a delete. And GitHub Actions cache entries written by actions/cache or a registry cache tag are a different store entirely, untouched by this endpoint.

When a reset is the right move

A reset clears the whole profile disk, so every image built on that profile rebuilds from scratch afterwards, including the images that were fine. On backends keyed by a string, such as a registry cache tag or a GitHub Actions cache key, the cheap escape from a poisoned entry is to change the key and abandon it. A builder profile has an equivalent lever in the profile-name input: point the affected workflow at a second profile and the old disk stays warm for whatever else uses it. The second profile is a second builder VM with its own session billing, so that lever pays off when two pipelines want different base layers anyway.

Warpbuilds/build-push-action@v6 is documented as a drop-in replacement for docker/build-push-action@v6, so the upstream build-push-action inputs for pulling a fresh base and for skipping the cache on a single build apply unchanged. Reach for those first. Reach for the reset when the disk itself is the problem, which is where profile size matters: the 16 vCPU profile carries a 100GB disk, the 32 and 64 vCPU profiles carry 200GB, and the largest amd64 profiles carry 600GB or 2TB. A 100GB profile that serves four images across two base image families runs out of headroom sooner than the size chart suggests.

What the next build costs after a reset

Builders are billed per session, measured from when the builder action starts until the job completes, and concurrent jobs sharing a profile share one session. The job runner and the builder are separate resources and both are billed. Rates from the pricing page, checked on 2026-08-13:

The arm64 and multi-architecture profiles top out at 64 vCPU, so the four largest sizes are amd64 only. A multi-architecture build also opens one session per architecture, because each architecture runs on its own builder instance, and each of those instances keeps its own layers, so a multi-architecture profile pays the cold rebuild on each architecture once its cache is cleared.

The cost of a reset is one cold build per image on the profile. Take the cold-minus-warm delta from your own job log, call it D minutes, and the bill is D multiplied by the builder rate plus D multiplied by the runner rate. The table below holds D at 6 minutes so the rate arithmetic stays visible, with the job running on warp-ubuntu-latest-x64-4x at $0.008 per minute:

Multiply by the number of images the profile serves, since each one pays the delta on its next build. A 64 vCPU profile serving five images is around $7.44 of rebuild for one reset on those assumptions, which is small against a weekly build volume and large enough that a nightly reset cron is the wrong instinct.

Timing the reset

Multiple jobs can run in parallel on one builder profile, and the cache between concurrent builds is shared but eventually consistent: a layer produced by one in-flight build may not reach another until it syncs. Right after a reset that property costs the most, because several builds started at once all find an empty disk and each rebuilds the same base layers. Run the reset in a quiet window and let one build repopulate the cache before the next wave arrives.

There is an automatic version of the same operation. The builder cache has a TTL of 10 days, and a profile that goes unused for longer than 10 days is reset automatically, so a profile that has already been idle that long needs no manual call. When the reset follows a base image change, trigger the rebuild on the new base first so the fresh disk fills with the layers you actually want.

The builder runs outside the job on its own VM, so the job only has to reach it over the WarpBuild API.

Related Questions

Does resetting the cache delete the builder profile?

No. The reset clears the layer cache on the profile's builder VM and leaves the profile in place, so its name, size, and architectures are unchanged and every workflow that names the profile keeps working. Deleting a profile is a separate action in the dashboard, and it requires waiting for in-flight builds to finish first. WarpBuild remote Docker builders lists the profile sizes and what each one holds.

Do I have to reset the cache after a base image update?

Usually no. A build that pulls the new base invalidates the FROM layer and every layer after it, so the affected layers rebuild themselves on the next run and the unrelated ones stay warm. Reset when repeated base bumps have left enough dead layers on the profile disk to matter. Why Docker builds lose cache after a base image update walks through the invalidation chain.

What does the first build after a reset cost?

It runs cold, so you pay the cold-minus-warm minute delta once per image, on the builder session and on the job runner. On a 16 vCPU profile at $0.06 per minute, a 6 minute delta is $0.36 on the builder plus $0.048 on a warp-ubuntu-latest-x64-4x runner at $0.008 per minute. The pricing page carries the rate for every profile size, and Docker builder profiles for GitHub Actions covers how many profiles a repository should have.