Cache Volumes - Namespace Documentation

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

Skip to main content

Assistant

Responses are generated using AI and may contain mistakes.

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:

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.

​ 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:

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:

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

​ 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:

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

Example Scenario:

You don’t always need two weeks of data: if the configured size already dwarfs what your jobs use (for example, a 50GB cache holding only ~200MB), reduce it early and continue monitoring.

​ API Access

Cache volumes can be managed programmatically via the StorageService API, which provides RPCs for listing volumes and tag summaries, and destroying cache volume tags.

Last modified onOctober 2, 2026

Ctrl+I

{"docsConfig":{"theme":"almond","$schema":"https://mintlify.com/docs.json","name":"Namespace Documentation","colors":{"primary":"#1C32FF","light":"#6B78FF","dark":"#1C32FF"},"logo":{"light":"https://mintcdn.com/namespace-labs/qOJQ7kaWRgoS8lyv/logo-light.svg?fit=max\\u0026auto=format\\u0026n=qOJQ7kaWRgoS8lyv\\u0026q=85\\u0026s=6827b0c81c335badc1cef13b83383e1d","dark":"https://mintcdn.com/namespace-labs/qOJQ7kaWRgoS8lyv/logo-dark.svg?fit=max\\u0026auto=format\\u0026n=qOJQ7kaWRgoS8lyv\\u0026q=85\\u0026s=63702d83d8fb259023deb79db06aabbb","href":"https://namespace.so"},"favicon":"https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/favicon.svg?fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=6f14a088da55e5f41847845796737353","navbar":{"links":\[{"href":"https://namespace.so/changelog","label":"Changelog"},{"href":"https://namespace.so/support","label":"Support"}\],"primary":{"type":"button","label":"Log in","href":"https://cloud.namespace.so"}},"footer":{"socials":{"github":"https://github.com/namespacelabs","linkedin":"https://www.linkedin.com/company/namespacelabs","x":"https://x.com/namespacelabs"}},"icons":{"library":"lucide"},"contextual":{"options":\["copy","view","chatgpt","claude"\],"display":"header"},"interaction":{"drilldown":false},"metadata":{"timestamp":true},"styling":{"latex":true},"navigation":{"global":{"anchors":\[{"anchor":"Changelog","icon":"history","href":"https://namespace.so/changelog"},{"anchor":"Trust Center (SOC2)","icon":"shield-check","href":"https://trust.namespace.so/"},{"anchor":"Status","icon":"activity","href":"https://namespace-status.com/"},{"anchor":"Support","icon":"message-circle","href":"https://namespace.so/support"}\]},"pages":\[\]}},"deployment":{"deploymentMetadataValue":{"subdomain":"namespace-labs","hasAudioNarration":false,"actualSubdomain":"namespace-labs","customDomains":\["namespace.so"\],"gitSource":{"type":"github","owner":"namespacelabs","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ae0862207896b4595e1934b","collectionId":"847aecca-4a0b-40b4-a393-e976cc214b43","liveDeploymentHistoryId":"6ae0862207896b4595e1934b","schemaVersion":"v3"},"entitlements":{"AI\_CHAT":{"status":"ENABLED"},"WEB\_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae0a8f6edbd4c098a94623c","clientVersion":"0.0.3971","searchFilterCounts":\[{"language":"default","tag":"Products","count":377},{"language":"default","tag":"CLI","count":166},{"language":"default","tag":"Command line","count":165},{"language":"default","tag":"Namespace CLI","count":131},{"language":"default","tag":"Documentation","count":104},{"language":"default","tag":"GitHub Actions","count":40},{"language":"default","tag":"Devbox CLI","count":34},{"language":"default","tag":"Integrations","count":33},{"language":"default","tag":"SDK","count":25},{"language":"default","tag":"Namespace SDK","count":23}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":true},"customCss":[{"filePath":"snippets/diagrams/styles.css","content":".ns-diagram{--ns-diagram-background:#ffffff;--ns-diagram-grid:#e5e7ee;--ns-diagram-border:#e5e7ee;--ns-diagram-card:#ffffff;--ns-diagram-neutral-zone:#fafbfc;--ns-diagram-brand-zone-start:rgba(28, 50, 255, 0.04);--ns-diagram-brand-zone-end:rgba(28, 50, 255, 0.07);--ns-diagram-brand-border:#c8ceff;--ns-diagram-heading:#202938;--ns-diagram-muted:#8892a6;--ns-diagram-copy:#4a5468;position:relative;width:100%;margin:2rem 0;padding:clamp(20px,3.5vw,32px);overflow:hidden;color:var(--ns-diagram-heading);background:var(--ns-diagram-background);border:1px solid var(--ns-diagram-border);border-radius:20px;box-shadow:0 1px 0 rgba(32,41,56,.04),0 1px 2px rgba(32,41,56,.06)}.dark .ns-diagram{--ns-diagram-background:#111827;--ns-diagram-grid:#374151;--ns-diagram-border:#374151;--ns-diagram-card:#1f2937;--ns-diagram-neutral-zone:#171f2d;--ns-diagram-brand-zone-start:rgba(107, 120, 255, 0.1);--ns-diagram-brand-zone-end:rgba(107, 120, 255, 0.16);--ns-diagram-brand-border:#4f5fc7;--ns-diagram-heading:#f3f4f6;--ns-diagram-muted:#aeb6c5;--ns-diagram-copy:#cbd5e1}.ns-diagram-grid-background{position:absolute;inset:0;pointer-events:none;background-image:radial-gradient(circle,var(--ns-diagram-grid) 1px,transparent 1px);background-size:16px 16px;opacity:.5;mask-image:linear-gradient(180deg,transparent 0,#000 10%,#000 90%,transparent 100%)}.ns-diagram-content{position:relative}.ns-diagram-caption{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.ns-diagram-mark{display:inline-flex;flex-shrink:0;align-items:center;justify-content:center;margin:0;border-radius:8px}.ns-diagram-mark-anthropic{color:#d97757;background:#fcefe8}.ns-diagram-mark-devin{color:#4338ca;background:#eef0ff}.ns-diagram-mark-cursor{color:#111827;background:#eef0f3}.ns-diagram-mark-control{color:#1c32ff;background:#e0e7ff}.ns-diagram-mark-terminal{color:#fff;background:#202938}.ns-diagram-mark-worker{color:#4338ca;background:#eef1ff}.ns-diagram-zone{position:relative;display:flex;flex-direction:column;padding:1.25rem;background:var(--ns-diagram-neutral-zone);border:1px dashed #d2d6e0;border-radius:14px}.dark .ns-diagram-zone{border-color:#4b5563}.ns-diagram-zone-brand{background:linear-gradient(180deg,var(--ns-diagram-brand-zone-start),var(--ns-diagram-brand-zone-end));border:1px solid var(--ns-diagram-brand-border)}.ns-diagram-zone-header{display:flex;align-items:center;gap:.5rem;margin-bottom:.75rem;color:var(--ns-diagram-copy);font-size:11px;font-weight:600;letter-spacing:.1em;text-transform:uppercase}.ns-diagram-zone-center{display:flex;flex:1;align-items:center}.ns-diagram-zone-center>*{width:100%}.ns-diagram-card{position:relative;display:flex;align-items:center;gap:1rem;min-width:0;padding:1rem 1.25rem;background:var(--ns-diagram-card);border:1px solid var(--ns-diagram-border);border-radius:12px;box-shadow:0 1px 0 rgba(32,41,56,.04),0 1px 2px rgba(32,41,56,.06)}.ns-diagram-card-brand{border-color:var(--ns-diagram-brand-border)}.ns-diagram-card-copy{display:flex;min-width:0;flex-direction:column}.ns-diagram-card-label{color:var(--ns-diagram-heading);font-size:16px;font-weight:600;line-height:1.25;letter-spacing:-.01em}.ns-diagram-card-sublabel{margin-top:.125rem;color:var(--ns-diagram-muted);font-size:12px;line-height:1.35}.ns-managed-layout{display:grid;grid-template-columns:1fr auto 1.05fr;align-items:stretch}.ns-managed-connector{display:flex;width:64px;flex-direction:column;align-items:center;justify-content:center;padding:0 .25rem;color:var(--ns-diagram-muted);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10.5px}.ns-managed-connector>span{margin-bottom:.375rem}.ns-managed-connector-path{display:flex;width:56px;align-items:center}.ns-managed-connector-line{flex:1;height:1.5px;background:#d2d6e0}.ns-managed-connector-arrow{border-top:6px solid transparent;border-bottom:6px solid transparent;border-left:9px solid #d2d6e0}.ns-mini-connector{display:flex;flex-direction:column;align-items:center;padding:.375rem 0}.ns-mini-connector>div{width:1.5px;height:12px;background:var(--ns-diagram-brand-border)}.ns-mini-connector>span{border-top:7px solid var(--ns-diagram-brand-border);border-right:5px solid transparent;border-left:5px solid transparent}.ns-devin-devboxes,.ns-devin-sessions{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:1.5rem}.ns-devin-mobile-layout{display:none}.ns-devin-connectors,.ns-devin-connectors>div{display:grid;grid-template-columns:repeat(2,minmax(0,1fr))}.ns-devin-connectors{gap:1.5rem}.ns-devin-connectors>div{padding:0 1rem}.ns-devin-connector{position:relative;display:flex;min-height:110px;align-items:center;justify-content:center;color:var(--ns-diagram-copy);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10px;line-height:1.25;text-align:center}.ns-devin-management-connector{min-height:70px;color:#6366f1}.ns-devin-connector-line{position:absolute;top:0;bottom:0;left:50%;width:1.5px;background:#d2d6e0;transform:translateX(-50%)}.ns-devin-management-connector .ns-devin-connector-line,.ns-diagram-connector-dashed .ns-diagram-vertical-line{width:0;background:0 0;border-left:1.5px dashed var(--ns-diagram-brand-border)}.ns-devin-connector>span,.ns-diagram-vertical-connector>span{position:relative;z-index:1;padding:0 .375rem;background:var(--ns-diagram-background)}.ns-control-plane-pill{display:flex;align-items:center;align-self:center;gap:.375rem;margin-bottom:1rem;padding:.375rem .75rem;color:#4338ca;background:#eef1ff;border:1px solid var(--ns-diagram-brand-border);border-radius:999px;font-size:12px;font-weight:500}.ns-diagram-vertical-connector{position:relative;display:flex;align-items:center;justify-content:center;color:var(--ns-diagram-copy);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10px;line-height:1.25;text-align:center}.ns-diagram-vertical-line{position:absolute;top:0;bottom:0;left:50%;width:1.5px;background:#d2d6e0;transform:translateX(-50%)}.ns-diagram-connector-dashed{color:#6366f1}.ns-diagram-arrow-down{position:absolute;bottom:0;left:50%;border-top:8px solid #d2d6e0;border-right:5px solid transparent;border-left:5px solid transparent;transform:translateX(-50%)}.ns-devin-management-connector .ns-diagram-arrow-down,.ns-diagram-connector-dashed .ns-diagram-arrow-down{border-top-color:var(--ns-diagram-brand-border)}.ns-bazel-connector-inset{padding:0 1rem}.ns-bazel-workers{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:1rem}@media (max-width:767px){.ns-managed-layout{grid-template-columns:1fr}.ns-managed-connector{position:relative;width:auto;min-height:64px;padding:.5rem 0}.ns-managed-connector-path{width:auto;flex-direction:column}.ns-managed-connector-line{width:1.5px;height:24px;flex:none}.ns-managed-connector-arrow{border-top:9px solid #d2d6e0;border-right:6px solid transparent;border-bottom:0;border-left:6px solid transparent}.ns-devin-connectors,.ns-devin-devboxes,.ns-devin-sessions{grid-template-columns:1fr}.ns-devin-desktop-layout{display:none}.ns-devin-mobile-layout{display:block}.ns-devin-mobile-lane+.ns-devin-mobile-lane{margin-top:1.5rem;padding-top:1.5rem;border-top:1px solid var(--ns-diagram-border)}.ns-devin-mobile-connectors{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));padding:0 .5rem}.ns-devin-connector{min-height:80px}.ns-bazel-workers{grid-template-columns:1fr}}"},{"filePath":"style.css","content":":root{--namespace-radius-inline:0.25rem;--namespace-radius-control:0.375rem;--namespace-radius-container:0.5rem}#content-container,.almond-layout>div,.card,.chat-assistant-floating-input>div,.code-block,.frame,.pagination-next,.pagination-prev{border-radius:var(--namespace-radius-container)}.code-block [data-component-part=code-block-root],.frame>div{border-radius:inherit}#assistant-entry,#chat-assistant-textarea,#search-bar-entry,#search-input,.callout,.frame>.relative{border-radius:var(--namespace-radius-control)}.code-block-fade-overlay{border-radius:0 var(--namespace-radius-container) var(--namespace-radius-container) 0}#page-context-menu>button:first-child{border-radius:var(--namespace-radius-control) 0 0 var(--namespace-radius-control)}#page-context-menu>button:last-child{border-radius:0 var(--namespace-radius-control) var(--namespace-radius-control) 0}#content :not(pre)>code,#navigation-items li>a,#navigation-items li>button{border-radius:var(--namespace-radius-inline)}#navigation-items .nav-anchor>:is(svg, img),#navigation-items .sidebar-group-icon,#navigation-items [data-component-part=scroll-area-content]:has(>ul.nav-anchors),#navigation-items li>:is(a, button)>div[class=\"h-[1lh]\"]:first-child{display:flex;flex-direction:column}#navigation-items [data-component-part=scroll-area-content]>ul.nav-anchors{order:1;margin-top:1rem;padding-top:1rem;border-top:1px solid color-mix(in srgb,currentColor 10%,transparent)}#navigation-items [data-component-part=scroll-area-content]>ul.sidebar-group{margin-top:.5rem}#navigation-items [data-component-part=scroll-area-content]>ul.sidebar-group+div{margin-top:1rem}.tab-container{overflow:hidden;padding:0 1rem 1rem;border:1px solid color-mix(in srgb,currentColor 12%,transparent);border-radius:var(--namespace-radius-container)}.tab-container [data-component-part=tab-content]>[data-table-wrapper]:last-child{margin-bottom:0;padding-bottom:0}#content .katex-display>.katex{text-align:left}.compact-table table td{min-width:0}#navigation-items ul.sidebar-group>li.space-y-px+li.space-y-px{margin-top:.75rem}#navigation-items .my-2>.sidebar-group-header{margin-bottom:.625rem;font-size:.8125rem;line-height:1.625rem;font-weight:600;letter-spacing:-.02em;text-transform:none;opacity:1}#navigation-items ul.sidebar-group>li.space-y-px>button{font-size:.8125rem;font-weight:600;letter-spacing:-.02em;background-color:transparent}#navigation-items ul.sidebar-group>li.space-y-px>button:hover,#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button:hover{background-color:color-mix(in srgb,currentColor 6%,transparent)}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button,#navigation-items ul.sidebar-group>li.space-y-px>ul>li>a{padding-left:3rem!important;font-size:.8125rem;font-weight:400;letter-spacing:-.02em}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li[data-active-nav-item=true]>a,#navigation-items ul.sidebar-group>li.space-y-px>ul>li[data-active-nav-item=true]>a{color:#121516!important;background-color:rgb(18 21 22/6%)!important}.dark #navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li[data-active-nav-item=true]>a,.dark #navigation-items ul.sidebar-group>li.space-y-px>ul>li[data-active-nav-item=true]>a{color:#f4f4f5!important;background-color:rgb(255 255 255/8%)!important}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button{background-color:transparent}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button>div[class=\"h-[1lh]\"]:first-child{margin-left:-1.75rem}.dark #navigation-items img[src*=buildkite-mark]{filter:brightness(.7)}.dark img[src*=\"/icons/apple.svg\"]{filter:invert(1)}.dark img.tab-icon[src*=\"/icons/linux.svg\"]{filter:invert(.35) brightness(1.54)}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li>a{padding-left:4rem!important;font-size:.8125rem;font-weight:400;letter-spacing:-.02em}@media (min-width:1024px){#sidebar-content{width:calc(16.5rem + 10px)}#content-container{margin-left:calc(16.5rem + 10px)}#navbar{container-type:inline-size}#navbar .nav-tabs{position:fixed;top:0;left:20rem;height:3.5rem;column-gap:2rem}#navbar div:has(>div>.nav-tabs){justify-content:flex-end}@container (max-width: 69rem){#navbar .navbar-link:has(>a[href=\"https://namespace.so/changelog\\"\]){display:none}}}@media (min-width:1280px){#content-container{padding-right:1.5rem;padding-left:3rem}#content-container>div{column-gap:1.5rem;justify-content:flex-start}#content-area{width:calc(100% - 13.5rem);max-width:52rem;flex:none}#content-side-layout{width:15rem;max-width:15rem;flex-basis:15rem}#content-side-layout>div{width:15rem;padding-left:1rem}#content-side-layout>div>div{width:14rem}}@media (min-width:1700px){#content-container>div{justify-content:center}}"},{"filePath":"reference/github-actions/runner-configuration.css","content":""},{"filePath":"workspaces/access.css","content":""},{"filePath":"platform/workspaces/access.css","content":""},{"filePath":"reference/devbox-cli/desktop.css","content":""}],"page":{"pagePath":"platform/storage/cache-volumes","slug":"/platform/storage/cache-volumes","pageMetadata":{"title":"Cache Volumes","noindex":true,"description":null,"href":"/platform/storage/cache-volumes"},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Frame,Heading,Info,OptimizedImage}=_components;if(!Frame)_missingMdxReference(`Frame`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!OptimizedImage)_missingMdxReference(`OptimizedImage`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Namespace Cache Volumes provide high-performance storage that can be attached to compute instances to accelerate your development workflows.\nBuilt on local NVMe storage, Cache Volumes are designed to handle the demanding I/O requirements of modern CI/CD pipelines and development environments.`}),`\n`,_jsx(_components.p,{children:_jsx(_components.a,{href:`/solutions/github-actions/caching`,children:`Learn how to use Cache Volumes`})}),`\n`,_jsx(Heading,{level:`2`,id:`multi-writer-safety`,children:`Multi-Writer Safety`}),`\n`,_jsx(_components.p,{children:`Cache Volumes can safely be accessed concurrently, allowing multiple runners to read and write cache data simultaneously.\nWhen you request a Cache Volume, Namespace creates a fork of the most recent cache version.\nEach compute instance receives its own private copy of the Cache Volume as it existed at the time of the last successful cache commit.`}),`\n`,_jsx(Heading,{level:`2`,id:`lifecycle-management`,children:`Lifecycle Management`}),`\n`,_jsx(_components.p,{children:`Cache Volumes follow a “last write wins” model for version management:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`First Request`}),`: Creates an empty cache volume as the initial version`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Subsequent Requests`}),`: New instances receive forks of the most recent committed version`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Successful Completion`}),`: When an instance terminates cleanly (exit code 0), its cache state becomes the new parent version`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Failed Instances`}),`: Cache changes from failed instances are automatically discarded`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`There may be multiple versions of a Cache Volume alive at the same time.`}),`\n`,_jsx(Heading,{level:`2`,id:`naming-and-access-control`,children:`Naming and Access Control`}),`\n`,_jsx(_components.p,{children:`Cache Volumes are identified by unique tags that govern access across your workspace.\nAny 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.\nEach tag maintains a versioned history of cache states, with Namespace automatically selecting the most appropriate version for new instances.`}),`\n`,_jsx(Heading,{level:`2`,id:`sizing-and-storage-management`,children:`Sizing and Storage Management`}),`\n`,_jsx(Heading,{level:`3`,id:`dynamic-sizing`,children:`Dynamic Sizing`}),`\n`,_jsx(_components.p,{children:`When requesting a Cache Volume, you specify a minimum space requirement.\nNamespace ensures your instance always has at least that amount of available space, but the actual volume size grows dynamically based on cached content.`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Configuration`}),`: 50GB Cache Volume`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`First instance`}),`: Starts with 50GB free space (0GB used)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`After storing 10GB`}),`: Volume contains 10GB used, 40GB free`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Second instance`}),`: Receives 60GB volume (10GB used from cache, 50GB free as requested)`]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`garbage-collection`,children:`Garbage Collection`}),`\n`,_jsxs(_components.p,{children:[`Namespace employs intelligent garbage collection strategies to maintain optimal cache performance and prevent `,_jsx(_components.a,{href:`#exceeding-cache-size`,children:`exceeding cache size`}),` that could lead to cache misses.`]}),`\n`,_jsx(_components.p,{children:`Garbage collection policies are available for:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Docker Image caching`}),`\n`,_jsx(_components.li,{children:`Local build caching`}),`\n`,_jsx(_components.li,{children:`Bazel caching`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`For specialized garbage collection requirements, contact our `,_jsx(_components.a,{href:`mailto:support@namespace.so`,children:`support team`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`cache-hits-and-misses`,children:`Cache Hits and Misses`}),`\n`,_jsx(_components.p,{children:`Namespace consistently provisions Cache Volumes with close to zero impact on startup latency.\nTo achieve this, there may be rare scenarios of cache misses, to avoid delaying the startup.\nNamespace prefers the latest version over older versions.\nIf this fails, stale cache versions are preferred over cache misses.`}),`\n`,_jsx(_components.p,{children:`Applications using Cache Volumes should not assume that the cache contents match exactly the last committed version.`}),`\n`,_jsx(Heading,{level:`3`,id:`cache-volume-onboarding`,children:`Cache Volume Onboarding`}),`\n`,_jsx(_components.p,{children:`Cache misses are more common during the initial onboarding phase, because its cache contents are not yet present across the fleet.`}),`\n`,_jsx(_components.p,{children:`Each time a job is allocated to a machine that does not hold the cache, it experiences a cache miss.\nWhen the job completes successfully, Namespace commits its cache data for future jobs.\nA later job allocated to the same machine receives the cached data and gets a cache hit.`}),`\n`,_jsx(_components.p,{children:`This feedback loop drives distribution of your data to ensure consistent cache hits over time.\nThe 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.`}),`\n`,_jsx(Heading,{level:`3`,id:`exceeding-cache-size`,children:`Exceeding Cache Size`}),`\n`,_jsxs(_components.p,{children:[`Cache Volumes provide the cache size you ask for (see `,_jsx(_components.a,{href:`#dynamic-sizing`,children:`Dynamic Sizing`}),`).\nCached content can grow over time as jobs write more data into the volume.`]}),`\n`,_jsx(_components.p,{children:`If the content exceeds the configured cache size, Namespace resets the cache.\nThe next job receives an empty cache volume, which causes a cache miss.`}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Example Scenario:`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Configuration`}),`: 50GB Cache Volume`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Existing cache`}),`: 20GB of content`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`First instance`}),`: receives a 70GB volume (20GB used + 50GB free)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`After storing 31GB`}),`: Volume contains 51GB used, 19GB free`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Second instance`}),`: Receives an empty 50GB volume (cache miss - cache contents exceeded the configured limit)`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Recommendation`}),`:\nTo avoid repeated cache resets, monitor your cache usage and adjust the configured cache size for `,_jsx(_components.a,{href:`https://cloud.namespace.so/workspace/actions/profiles\`,children:\`your profile`}),` as needed.`]}),`\n`,_jsx(Heading,{level:`2`,id:`usage`,children:`Usage`}),`\n`,_jsxs(_components.p,{children:[`Namespace accounts Cache Volume usage in two categories: cache snapshot usage and cache storage.\nThey are billed independently and behave differently.\nYou can analyze both on the `,_jsx(_components.a,{href:`https://cloud.namespace.so/workspace/usage?focus=storage\`,children:\`Usage page`}),` of the dashboard.`]}),`\n`,_jsx(Heading,{level:`3`,id:`cache-snapshot-usage`,children:`Cache snapshot usage`}),`\n`,_jsx(_components.p,{children:`Cache snapshot usage is the active usage of a cache while it is attached to a running instance.\nOn a cache hit, Namespace accounts snapshot usage as the lifetime of the attached instance times the size of the cache volume.\nThis 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.\nIf an instance runs for 3 hours with a 50 GB cache volume attached, the metric would be 150 GB-hours.\nLarger caches increase this usage and faster runs reduce it. Snapshot usage typically dominates the cost of a cache volume.`}),`\n`,_jsx(Heading,{level:`3`,id:`cache-storage`,children:`Cache storage`}),`\n`,_jsx(_components.p,{children:`Cache storage is the at-rest cost of keeping your cache available so that Namespace can provision it onto new instances.\nA cache volume tag consumes storage proportional to the requested size of the volume, not the amount actually used.\nA 50 GB cache that only ever holds 10 GB of content still accounts storage for the full 50 GB.`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsxs(_components.p,{children:[`Cache storage accrues for as long as a cache generation is alive.\nEach new attachment to a cache tag refreshes its generation, so an actively used cache stays alive.\nNamespace automatically evicts cache volume generations after a grace period of inactivity.\nOnce a generation is evicted, it can no longer serve cache hits and stops counting towards your usage.\nIf you have specific requirements around cache volume expiration, `,_jsx(_components.a,{href:`mailto:support@namespace.so`,children:`contact our support team`}),`.\nTo evict a cache ahead of its expiration, you can release it from the `,_jsx(_components.a,{href:`https://cloud.namespace.so/workspace/storage\`,children:\`Cache Volumes page`}),` of the dashboard.`]}),`\n`,_jsxs(_components.p,{children:[`Because storage is usually a small fraction of total cache cost, reducing the retention window rarely produces meaningful savings.\nThe larger lever is right-sizing the cache, which lowers both snapshot and storage usage. See `,_jsx(_components.a,{href:`#choosing-the-right-cache-size`,children:`Choosing the Right Cache Size`}),`.`]}),`\n`,_jsx(Heading,{level:`3`,id:`example-for-github-runners`,children:`Example for GitHub runners`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Configuration`}),`: `,_jsx(_components.a,{href:`/solutions/github-actions#getting-started`,children:`runner profile`}),` with 50GB cache`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`First run`}),`: cache storage accounting begins, adds 50GB-days per day.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Second run`}),`: cache hit, runs for 10 minutes -> accounts for 500 GB-minutes.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Third run`}),`: cache miss -> does not count towards cache usage.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Another repository`}),`: If the same profile is used for a different repository, the cache is separate and usage is accounted separately.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`choosing-the-right-cache-size`,children:`Choosing the Right Cache Size`}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsxs(_components.p,{children:[`You can check actual usage for a tag in the `,_jsx(_components.a,{href:`https://cloud.namespace.so/workspace/storage\`,children:\`Cache Volumes page`}),` of the dashboard and adjust from there.`]}),`\n`,_jsx(Frame,{style:{maxWidth:800,marginInline:`auto`},children:_jsx(OptimizedImage,{src:`https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=6249374b734ffde8ba4d58208b29d617\`,alt:\`Dashboard Cache Volumes page`,width:1600,height:676,\"data-og-width\":`1600`,\"data-og-height\":`676`,\"data-path\":`images/architecture/cache-volumes-dashboard.png`,\"data-optimize\":`true`,\"data-opv\":`3`,srcset:`https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=280\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=49fce570b250478ae2c10d90281f084b 280w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=560\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=739fe693ebdad4e93e4037608e67803c 560w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=840\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=f14267583403035ce208d5f815d5f3dc 840w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=1100\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=cd7e119a31b81de64ed80eb7a8db4586 1100w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=1650\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=da41ca201c2a30c99baffccb3d3471c5 1650w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-dashboard.png?w=2500\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=5606d9ae85df6bb3df6f826b1b2288da 2500w`})}),`\n`,_jsxs(_components.p,{children:[`The two failure modes pull in opposite directions.\nA size that is `,_jsx(_components.strong,{children:`too small`}),` causes the cache to reset when content `,_jsx(_components.a,{href:`#exceeding-cache-size`,children:`exceeds the configured size`}),`, which produces cache misses and slower jobs.\nA size that is `,_jsx(_components.strong,{children:`too large`}),` avoids resets but costs more, since storage and snapshot usage are billed in proportion to the configured size (see `,_jsx(_components.a,{href:`#usage`,children:`Usage`}),`).`]}),`\n`,_jsx(Heading,{level:`3`,id:`method`,children:`Method`}),`\n`,_jsx(_components.p,{children:`Treat the size as a value to tune rather than set once:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Start`}),` large enough to avoid early resets.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Monitor`}),` usage for your cache tag across the first two weeks.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Adjust`}),` to the observed working set plus 20-30% headroom, so normal variation does not push the cache past its limit.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.strong,{children:`Example Scenario:`})}),`\n`,_jsx(Frame,{style:{maxWidth:800,marginInline:`auto`},children:_jsx(OptimizedImage,{src:`https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=6dda3e5c8b61847d46be56ca316ba94e\`,alt:\`Dashboard Cache Example`,width:1600,height:391,\"data-og-width\":`1600`,\"data-og-height\":`391`,\"data-path\":`images/architecture/cache-volumes-example.png`,\"data-optimize\":`true`,\"data-opv\":`3`,srcset:`https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=280\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=91d17259150c354c8b1dc1c6da39dc3d 280w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=560\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=f016c8303ae232c3bafa74acffdb00ee 560w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=840\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=0adef9749021effc64598786678c6722 840w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=1100\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=9ad6aef34776b6c7aa600c83d83b412d 1100w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=1650\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=ddcf09f9cef00c8816ed3e1e808d4a47 1650w, https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/images/architecture/cache-volumes-example.png?w=2500\\u0026fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=af1cbfba33f8763e2317cd1af630df3c 2500w`})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Start`}),`: configure a 50GB Cache Volume to be safe against early resets`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Monitor`}),`: after two weeks, the Cache Volumes page shows usage peaking around 12GB`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Adjust`}),`: configure 16GB (12GB working set + ~30% headroom), cutting the billed size by more than two thirds while keeping room for variation`]}),`\n`]}),`\n`,_jsx(Info,{children:_jsx(_components.p,{children:`You don’t always need two weeks of data: if the configured size already dwarfs what your jobs use (for example, a 50GB cache holding only ~200MB), reduce it early and continue monitoring.`})}),`\n`,_jsx(Heading,{level:`2`,id:`api-access`,children:`API Access`}),`\n`,_jsxs(_components.p,{children:[`Cache volumes can be managed programmatically via the\n`,_jsx(_components.a,{href:`https://buf.build/namespace/cloud/docs/main:namespace.cloud.compute.v1beta\`,children:\`StorageService API`}),`,\nwhich provides RPCs for listing volumes and tag summaries, and destroying cache volume tags.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Cache Volumes","noindex":true,"description":null,"href":"/platform/storage/cache-volumes"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Multi-Writer Safety","slug":"multi-writer-safety","depth":2,"children":[]},{"title":"Lifecycle Management","slug":"lifecycle-management","depth":2,"children":[]},{"title":"Naming and Access Control","slug":"naming-and-access-control","depth":2,"children":[]},{"title":"Sizing and Storage Management","slug":"sizing-and-storage-management","depth":2,"children":[{"title":"Dynamic Sizing","slug":"dynamic-sizing","depth":3,"children":[]},{"title":"Garbage Collection","slug":"garbage-collection","depth":3,"children":[]}]},{"title":"Cache Hits and Misses","slug":"cache-hits-and-misses","depth":2,"children":[{"title":"Cache Volume Onboarding","slug":"cache-volume-onboarding","depth":3,"children":[]},{"title":"Exceeding Cache Size","slug":"exceeding-cache-size","depth":3,"children":[]}]},{"title":"Usage","slug":"usage","depth":2,"children":[{"title":"Cache snapshot usage","slug":"cache-snapshot-usage","depth":3,"children":[]},{"title":"Cache storage","slug":"cache-storage","depth":3,"children":[]},{"title":"Example for GitHub runners","slug":"example-for-github-runners","depth":3,"children":[]}]},{"title":"Choosing the Right Cache Size","slug":"choosing-the-right-cache-size","depth":2,"children":[{"title":"Method","slug":"method","depth":3,"children":[]}]},{"title":"API Access","slug":"api-access","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/docs/_mintlify/custom/namespace-labs/fa018fe02fd436c8/navigation.js","/docs/_mintlify/custom/namespace-labs/4276600b7cb636ff/legacy-anchor-redirects.js"],"subdomain":"namespace-labs","siteName":"Namespace Documentation","title":"Cache Volumes - Namespace Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-26T10:46:17.778Z","gitLastModified":"2026-10-02T14:07:39.000Z","originalFileLocation":"platform/storage/cache-volumes.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"application-name\" content=\"Namespace Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"noindex\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Cache Volumes - Namespace Documentation\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Namespace Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://namespace.so/docs/platform/storage/cache-volumes\\">\\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://namespace-labs.mintlify.app/\_mintlify/api/og/v2?division=Storage\\u0026amp;title=Cache+Volumes\\u0026amp;theme=1f89d53762a6d5304d1c63c4\\u0026amp;signature=500d5977fe2c8ced1fe437d2d1c9d05c2c2c0fbfa902d83852244d477b77355e\\">\\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Cache Volumes - Namespace Documentation\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://namespace-labs.mintlify.app/\_mintlify/api/og/v2?division=Storage\\u0026amp;title=Cache+Volumes\\u0026amp;theme=1f89d53762a6d5304d1c63c4\\u0026amp;signature=500d5977fe2c8ced1fe437d2d1c9d05c2c2c0fbfa902d83852244d477b77355e\\">\\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Namespace Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#1C32FF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://namespace.so/docs/platform/storage/cache-volumes\\">\\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/platform/storage/cache-volumes.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\\",\\"@type\\":\\"WebSite\\",\\"name\\":\\"Namespace Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\\"}}\\u003c/script>","siteName":"Namespace Documentation","nav":{"global":{"anchors":[{"anchor":"Changelog","icon":"history","href":"https://namespace.so/changelog"},{"anchor":"Trust Center (SOC2)","icon":"shield-check","href":"https://trust.namespace.so/"},{"anchor":"Status","icon":"activity","href":"https://namespace-status.com/"},{"anchor":"Support","icon":"message-circle","href":"https://namespace.so/support"}\]},"products":\[{"product":"Products","description":"Turnkey products built on the Namespace platform","pages":[{"title":"Products","href":""}]},{"product":"Platform","description":"Lower-level primitives to build your own","tabs":[{"tab":"Documentation","icon":"book-open","pages":[{"title":"Start building with Namespace","sidebarTitle":"Overview","href":"/platform"},{"group":"Build with Namespace","pages":[{"group":"Authentication","icon":"key-round","pages":[{"title":"Authentication for Platforms","sidebarTitle":"Overview","href":"/platform/authentication/index"},{"title":"Build on Your Own Workspace","sidebarTitle":"Build on your own workspace","href":"/platform/authentication/local-development"},{"title":"Partner Credentials","sidebarTitle":"Partner credentials","href":"/platform/authentication/partner-credentials"},{"title":"Tenant Tokens","sidebarTitle":"Tenant tokens","href":"/platform/authentication/tenant-tokens"},{"title":"Revokable Tokens","sidebarTitle":"Revokable tokens","href":"/platform/authentication/revokable-tokens"}]},{"group":"Multi-tenancy","icon":"users","pages":[{"title":"Multi-tenancy","sidebarTitle":"Overview","href":"/platform/tenants/index"},{"title":"Create a Tenant with the Platform API","sidebarTitle":"Quickstart","href":"/platform/tenants/quickstart"},{"title":"Partner and Tenant Clients","sidebarTitle":"Partner and tenant clients","href":"/platform/tenants/clients"},{"title":"Create Tenants","sidebarTitle":"Create tenants","href":"/platform/tenants/create"},{"title":"List Tenants","sidebarTitle":"List and find tenants","href":"/platform/tenants/list"},{"title":"Update Tenants","sidebarTitle":"Update tenants","href":"/platform/tenants/update"},{"title":"Tenant Policies","sidebarTitle":"Tenant policies","href":"/platform/tenants/policies"},{"title":"Delete Tenants","sidebarTitle":"Delete tenants","href":"/platform/tenants/delete"}]},{"group":"Instances","icon":"server","pages":[{"title":"Create an Instance with the Platform API","sidebarTitle":"Quickstart","href":"/platform/instances/quickstart"},{"title":"Instance Configuration","sidebarTitle":"Configuration","href":"/platform/instances/configuration"},{"group":"Examples","icon":"code","pages":[{"title":"Run a Command in an Instance","sidebarTitle":"Run commands","href":"/platform/instances/examples/run-commands"},{"title":"Create or Reuse an Instance","sidebarTitle":"Create or reuse","href":"/platform/instances/examples/create-or-reuse"},{"title":"SSH into a Container","sidebarTitle":"SSH access","href":"/platform/instances/examples/ssh"},{"title":"Authenticating to an Instance Endpoint","sidebarTitle":"Endpoint authentication","href":"/platform/instances/examples/endpoint-authentication"},{"title":"Creating Many Instances Concurrently","sidebarTitle":"Concurrent instances","href":"/platform/instances/examples/concurrency"}]}]}]},{"group":"Building Blocks","pages":[{"group":"Compute","icon":"cpu","pages":[{"title":"Compute Platform","sidebarTitle":"Overview","href":"/platform/compute/index"},{"title":"Linux","href":"/platform/compute/linux"},{"title":"macOS","href":"/platform/compute/macos"},{"title":"Windows","href":"/platform/compute/windows"},{"title":"Observability","href":"/platform/compute/observability"},{"title":"SSH / Remote Display with Namespace Compute","sidebarTitle":"SSH / Remote Display","href":"/platform/compute/ssh-remote-display"},{"title":"Machine Shapes","href":"/platform/compute/machine-shapes"},{"title":"Resource Limits","href":"/platform/compute/resource-limits"}]},{"group":"Storage","icon":"database","pages":[{"title":"Storage","sidebarTitle":"Overview","description":null,"href":"/platform/storage/index"},{"title":"Cache Volumes","href":"/platform/storage/cache-volumes"},{"title":"Container Registry","description":null,"href":"/platform/storage/container-registry"},{"title":"Artifact Storage","href":"/platform/storage/artifact-storage"},{"title":"Secrets","href":"/platform/storage/secrets"}]},{"group":"Networking","icon":"network","pages":[{"title":"Networking","sidebarTitle":"Overview","href":"/platform/networking/index"},{"title":"Ingress","href":"/platform/networking/ingress"},{"title":"Network Performance Optimizations","sidebarTitle":"Performance","href":"/platform/networking/performance"},{"title":"Network Security","sidebarTitle":"Security","href":"/platform/networking/security"},{"title":"Egress policies","href":"/platform/networking/egress-policy"}]}]}]}]}]},"title":"Cache Volumes - Namespace Documentation","buildId":"dpl_GvhK4qVXq51DpfYJLCtPpYNN4YHN","deploymentId":"dpl_GvhK4qVXq51DpfYJLCtPpYNN4YHN","dynamics":["07c022d89b","a74be98ba7"],"chunks":["Frame-5VlDM5Io.js","DynamicMarkdown-DO1Fz7ar.js","zoom-image-lightbox-uyuQJRFs.js","lightbox-handle-r17bVUz3.js"]}