---
title: Build caches
description: A per-project layer cache that makes builds faster and never changes their result — a missing or unreachable cache only slows a build.
type: explanation
product: builds
summary: The cache a build reads and writes, and why it can never change a result.
updated: 2026-10-01
order: 0
---

<Callout tone="note" title="Today this runs on the management API">
Builds use the project's layer cache automatically, and there is no cache call to make. The `build_caches` commands below are in the CLI's command list, but api.sylphx.com does not serve the collection.
</Callout>

A BuildCache is a per-project layer cache. A build that reads it does less
work than the build that filled it, which is the whole of what it is for.

It makes builds faster and never changes their result. That is the property
worth knowing: a build whose cache is missing or unreachable produces the same
image and the same digests, only slower. Nothing about a build's correctness
depends on a cache being there.

## What a build does with it

A build names the cache it reads and writes, and unset means the project's
default cache:

<PropertyTable
	properties={[
		{
			name: 'cache',
			type: 'string',
			description: 'The BuildCache to read and write; the project’s default cache by default.',
		},
	]}
/>

Because the cache belongs to the project rather than to one build, every build
of that project reads and writes the same cache. That is what makes the second
build of the same work cheap: the first one already paid for it.

## The one field you set, and the four you read

<PropertyTable
	properties={[
		{
			name: 'retention',
			type: 'duration',
			description: 'Entries unused this long are evicted.',
		},
	]}
/>

`retention` is the whole of the spec. It bounds how long an entry survives
without being read, which is why eviction under it costs time and never
correctness — the build that finds an entry gone rebuilds it. The reference
carries the default on [the update page](/docs/api/build_caches/update).

What the platform reports about a cache is read-only:

<PropertyTable
	properties={[
		{
			name: 'size_bytes',
			type: 'int64',
			description: 'Bytes stored.',
		},
		{
			name: 'last_use_time',
			type: 'timestamp',
			description: 'When a build last read the cache.',
		},
		{
			name: 'conditions',
			type: 'Condition[]',
			description: 'Ready, Reconciling, Stalled.',
		},
		{
			name: 'observed_generation',
			type: 'int64',
			description: 'The generation this status was computed from.',
		},
	]}
/>

`last_use_time` answers whether a cache is earning its keep: it is when a
build last read the cache, and an entry nothing reads is evicted once
`retention` runs out.

## Reading, changing and deleting one

A cache is read by name under its project, and the project's caches are one
list:

```bash
sylphx build build-caches get orgs/acme/projects/shop/build_caches/build-cache
```

```bash
sylphx build build-caches list orgs/acme/projects/shop
```

`update` changes the spec, with `update_mask` naming the fields to write and
`allow_missing` creating the cache when it does not exist:

```bash
sylphx build build-caches update orgs/acme/projects/shop/build_caches/build-cache
```

`delete` is `destructive`, so the CLI asks before it runs and takes `--yes`:

```bash
sylphx build build-caches delete orgs/acme/projects/shop/build_caches/build-cache --yes
```

Deleting a cache does not delete a build and does not change one: the next
build finds no entries and makes them again. The cost of a delete is the work
the cache was saving, and nothing else.

Reading a cache needs `build:read`; changing or deleting one needs
`build:write`. The collection, method by method, is in
[the build_caches reference](/docs/api/build_caches).

<RelatedDocs
	links={[
		{
			href: '/docs/api/build_caches/update',
			label: 'update',
			description: 'The spec field, the flags and the examples.',
		},
		{
			href: '/docs/api/build_caches',
			label: 'The build_caches collection',
			description: 'Every method, its scope and its examples.',
		},
		{
			href: '/docs/builds',
			label: 'Builds',
			description: 'What a build turns a commit into.',
		},
		{
			href: '/docs/cli/build_caches',
			label: 'The CLI commands',
			description: 'The same calls as sylphx build build-caches.',
		},
	]}
/>