Cache Volumes

Namespace Cache Volumes provide high-performance storage that can be attached to compute instances to accelerate your development workflows. Built on local NVMe storage, Cache Volumes are designed to handle the demanding I/O requirements of modern CI/CD pipelines and development environments.

Learn how to use Cache Volumes

Multi-Writer Safety

Cache Volumes can safely be accessed concurrently, allowing multiple runners to read and write cache data simultaneously. When you request a Cache Volume, Namespace creates a fork of the most recent cache version. Each compute instance receives its own private copy of the Cache Volume as it existed at the time of the last successful cache commit.

Lifecycle Management

Cache Volumes follow a "last write wins" model for version management:

First Request: Creates an empty cache volume as the initial version
Subsequent Requests: New instances receive forks of the most recent committed version
Successful Completion: When an instance terminates cleanly (exit code 0), its cache state becomes the new parent version
Failed Instances: Cache changes from failed instances are automatically discarded

There may be multiple versions of a Cache Volume alive at the same time.

Naming and Access Control

Cache Volumes are identified by unique tags that govern access across your workspace. Any compute instance can request access to a Cache Volume by specifying its tag, making it easy to share cached data across different workflows and jobs. Each tag maintains a versioned history of cache states, with Namespace automatically selecting the most appropriate version for new instances.

Sizing and Storage Management

Dynamic Sizing

When requesting a Cache Volume, you specify a minimum space requirement. Namespace ensures your instance always has at least that amount of available space, but the actual volume size grows dynamically based on cached content.

Configuration: 50GB Cache Volume
First instance: Starts with 50GB free space (0GB used)
After storing 10GB: Volume contains 10GB used, 40GB free
Second instance: Receives 60GB volume (10GB used from cache, 50GB free as requested)

Garbage Collection

Namespace employs intelligent garbage collection strategies to maintain optimal cache performance and prevent exceeding cache size that could lead to cache misses.

Garbage collection policies are available for:

Docker Image caching
Local build caching
Bazel caching

For specialized garbage collection requirements, contact our support team.

Cache Hits and Misses

Namespace consistently provisions Cache Volumes with close to zero impact on startup latency. To achieve this, there may be rare scenarios of cache misses, to avoid delaying the startup. Namespace prefers the latest version over older versions. If this fails, stale cache versions are preferred over cache misses.

Applications using Cache Volumes should not assume that the cache contents match exactly the last committed version.

Cache Volume Onboarding

Cache misses are more common during the initial onboarding phase, because its cache contents are not yet present across the fleet.

Each time a job is allocated to a machine that does not hold the cache, it experiences a cache miss. When the job completes successfully, Namespace commits its cache data for future jobs. A later job allocated to the same machine receives the cached data and gets a cache hit.

This feedback loop drives distribution of your data to ensure consistent cache hits over time.
The more jobs you run, the more machines in the fleet hold the cache data, and the cache hit rate rises until you see consistent hits.

Exceeding Cache Size

Cache Volumes provide the cache size you ask for (see Dynamic Sizing).
Cached content can grow over time as jobs write more data into the volume.

If the content exceeds the configured cache size, Namespace resets the cache.
The next job receives an empty cache volume, which causes a cache miss.

Example Scenario:

Configuration: 50GB Cache Volume
Existing cache: 20GB of content
First instance: receives a 70GB volume (20GB used + 50GB free)
After storing 31GB: Volume contains 51GB used, 19GB free
Second instance: Receives an empty 50GB volume (cache miss - cache contents exceeded the configured limit)

Recommendation: To avoid repeated cache resets, monitor your cache usage and adjust the configured cache size for your profile as needed.

Usage

Namespace accounts Cache Volume usage in two categories: cache snapshot usage and cache storage. They are billed independently and behave differently. You can analyze both on the Usage page of the dashboard.

Cache snapshot usage

Cache snapshot usage is the active usage of a cache while it is attached to a running instance. On a cache hit, Namespace accounts snapshot usage as the lifetime of the attached instance times the size of the cache volume. This gives a measurement in GB-hours. For example, if an instance runs for one hour with a 100 GB cache volume attached, the billable metric will be 100 GB-hours. If an instance runs for 3 hours with a 50 GB cache volume attached, the metric would be 150 GB-hours. Larger caches increase this usage and faster runs reduce it. Snapshot usage typically dominates the cost of a cache volume.

Cache storage

Cache storage is the at-rest cost of keeping your cache available so that Namespace can provision it onto new instances. A cache volume tag consumes storage proportional to the requested size of the volume, not the amount actually used. A 50 GB cache that only ever holds 10 GB of content still accounts storage for the full 50 GB.

Namespace replicates each cache across the fleet to improve cache hit rates, but storage is accounted only once, regardless of the number of replicas or the number of instances attached to the cache.

Cache storage accrues for as long as a cache generation is alive. Each new attachment to a cache tag refreshes its generation, so an actively used cache stays alive. Namespace automatically evicts cache volume generations after a grace period of inactivity. Once a generation is evicted, it can no longer serve cache hits and stops counting towards your usage. If you have specific requirements around cache volume expiration, contact our support team. To evict a cache ahead of its expiration, you can release it from the Cache Volumes page of the dashboard.

Because storage is usually a small fraction of total cache cost, reducing the retention window rarely produces meaningful savings. The larger lever is right-sizing the cache, which lowers both snapshot and storage usage. See Choosing the Right Cache Size.

Example for GitHub runners

Configuration: runner profile with 50GB cache
First run: cache storage accounting begins, adds 50GB-days per day.
Second run: cache hit, runs for 10 minutes -> accounts for 500 GB-minutes.
Third run: cache miss -> does not count towards cache usage.
Another repository: If the same profile is used for a different repository, the cache is separate and usage is accounted separately.

Choosing the Right Cache Size

Size the cache to the working set your jobs actually use, then add 20-30% headroom. The goal is to avoid resets without paying for unused cache capacity.

You can check actual usage for a tag in the Cache Volumes page of the dashboard and adjust from there.

The two failure modes pull in opposite directions. A size that is too small causes the cache to reset when content exceeds the configured size, which produces cache misses and slower jobs. A size that is too large avoids resets but costs more, since storage and snapshot usage are billed in proportion to the configured size (see Usage).

Method

Treat the size as a value to tune rather than set once:

Start large enough to avoid early resets.
Monitor usage for your cache tag across the first two weeks.
Adjust to the observed working set plus 20-30% headroom, so normal variation does not push the cache past its limit.