Remote Caching

Purpose and Scope

Remote Caching is the Turborepo feature that lets one machine reuse work performed by another machine. Local task caching already prevents repeated work on a single filesystem, but it cannot help when the same task is run by a teammate, a CI job, or a deployment platform on a different machine. The Remote Caching documentation frames the problem with turbo run build: if the task inputs are identical, repeating the build on every machine wastes time and compute. A remote cache changes that by storing task results in a shared service that the Turborepo CLI can read from and write to.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx

The feature is optional. Turborepo can speed up existing workflows using only local caching, and the docs explicitly say you do not need Remote Caching to use Turborepo. The reason to enable it is organizational: once the cache is shared, successful work from local development, CI, and platform builds can benefit everyone who runs the same cacheable task with the same recognized inputs. In practical terms, Remote Caching turns the “never do the same work twice” promise from a single-machine optimization into a team and pipeline optimization.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/docs/core-concepts/index.mdx

Relevant Source Files

• apps/docs/content/docs/core-concepts/remote-caching.mdx — Primary conceptual page for Remote Caching, including the local-cache problem, the shared-cache model, Vercel setup, authentication, linking, and safety guidance.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Product announcement that Vercel Remote Cache is free for linked Turborepos and summarizes setup for Vercel, other CI providers, and local machines.
• apps/docs/content/docs/crafting-your-repository/caching.mdx — General caching guide that explains deterministic tasks, cache fingerprints, .turbo/cache, local cache hits, and the handoff from local caching to Remote Caching.
• apps/docs/content/blog/joining-vercel.mdx — Historical context for Vercel-backed zero-configuration remote caching and the open-source CLI milestone.
• apps/docs/content/docs/core-concepts/index.mdx — Core concepts index that positions Remote Caching as one of the foundational Turborepo concepts.
• apps/docs/content/docs/core-concepts/internal-packages.mdx — Supporting concept page for internal packages, useful because package compilation strategy influences which package tasks produce reusable cache artifacts.

Core Concepts

A Turborepo cache entry is tied to a task fingerprint. The caching guide explains that when a task is cacheable, Turborepo restores results from a cache using a fingerprint from the first time the task ran. That fingerprint is derived from the inputs Turborepo knows about, and the guide warns that tasks should be deterministic: if a task can produce different outputs from the same recognized inputs, cache behavior may not match expectations. Remote Caching does not change that contract. It only changes where reusable task artifacts can be found.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx

The default local cache lives in the .turbo/cache directory on a developer machine. A first run of a task, such as a build in a newly created Turborepo, produces a cache miss because that input set has not been seen before in the repository. A second run can hit the cache because the fingerprint is already present. With Remote Caching enabled, the same lookup can include a shared cache, so a cache hit can come from work performed elsewhere rather than only from work performed earlier on the same machine.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/core-concepts/remote-caching.mdx

A remote cache stores more than final build directories. The Remote Caching page cautions that Turborepo treats logs as artifacts, so teams should be careful about what tasks print to the console. This warning belongs beside environment-variable and secret-handling practices, because Remote Caching makes artifacts available beyond the developer who originally ran the task. Before enabling it broadly, confirm that outputs, environment-variable hashing, and task commands describe the real inputs and safe artifacts of each cacheable task.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx

Authentication and Linking Flow

For Vercel Remote Cache in local development, the documented flow is two steps: authenticate the CLI, then link the repository. Authentication is performed with turbo login, or with the package-manager equivalent when turbo is not installed globally. Linking associates the repository on the local machine with the remote cache provider. The caching guide shows the same sequence using npx turbo login followed by npx turbo link, and the free Vercel Remote Cache announcement repeats those commands for local setup.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

npx turbo login
npx turbo link

After linking, normal task commands do not need to be rewritten just to use Remote Caching. The caching guide says that once authenticated and linked, Turborepo will automatically send task outputs to the Remote Cache when tasks run. The important operational detail is that Remote Caching is not a separate build command; it is an extension of the same task execution model. Your scripts can continue to call turbo run build, turbo run test, or package-manager scripts that delegate to turbo.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx

turbo run build
pnpm run build
npm run build
yarn build
bun run build

Vercel-hosted builds are described as zero-configuration for commands using turbo on Vercel. The free Remote Cache announcement states that Turborepos linked to Vercel automatically benefit from Vercel Remote Cache on Vercel. On other CI providers, the documented authentication mechanism is environment variables: create TURBO_TOKEN and TURBO_TEAM with their respective values. This distinction matters because local developers usually use interactive login and linking, while CI systems should authenticate non-interactively through configured secrets and variables.

Sources: apps/docs/content/blog/free-vercel-remote-cache.mdx

env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Artifact Sharing and Safety Model

Remote Caching is most valuable when multiple machines are likely to request the same task result. A CI build can populate the cache for a branch, a teammate can reuse the same build output later, and a deployment platform can avoid rebuilding unchanged packages when the fingerprint matches. The docs describe this as preventing duplicated work across an organization. That sharing model is why Remote Caching belongs in the core concepts section rather than only in CI documentation: it affects how the whole repository experiences task execution.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

The same sharing model also raises the bar for correct cache configuration. A task that reads undeclared inputs, relies on untracked environment variables, or writes outputs that are not described accurately may appear cacheable while still producing incorrect reuse. The caching guide introduces task inputs, outputs, and troubleshooting in the same page that points readers toward Remote Caching, and the Remote Caching page explicitly tells readers to make sure they are caching correctly first. Treat Remote Caching as a multiplier: it amplifies well-modeled tasks and can also amplify configuration mistakes.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx, apps/docs/content/docs/core-concepts/remote-caching.mdx

Internal package strategy can influence how much reusable work exists for Remote Caching. The internal packages documentation describes Just-in-Time packages as packages compiled by the application that uses them, and notes that this can be attractive when modern bundlers handle the package directly. That convenience may mean there is no separate package build artifact to reuse. Compiled or publishable package strategies create explicit build steps and outputs, which are easier to model as cacheable tasks when the repository needs shared artifacts across applications, developers, and CI.

Sources: apps/docs/content/docs/core-concepts/internal-packages.mdx

Command and Configuration Reference

The repository docs also preserve product history around Vercel-backed caching. The “joining Vercel” announcement says the Turborepo CLI became open source and that Turborepo provides zero-config remote caching through Vercel. The later free Remote Cache announcement updates that story by stating Vercel Remote Cache is free for any Turborepo linked to Vercel, including repositories that do not host applications on Vercel. For current user workflows, prefer the modern setup guidance: Vercel is automatic on Vercel, local machines use login and link, and other CI providers use token and team variables.

Sources: apps/docs/content/blog/joining-vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Execution Flow

A practical rollout starts with local caching, not remote infrastructure. First, make sure a task can hit the local cache twice in a row. The caching guide’s learning path has users create a Turborepo, run a build once to produce a miss, then run it again to see a cache hit. That sequence proves that Turborepo recognizes the task inputs and outputs well enough for reuse. Only after that should the team add Remote Caching, because the remote service depends on the same fingerprinting and artifact model.

Sources: apps/docs/content/docs/crafting-your-repository/caching.mdx

Second, connect developers and CI through the appropriate authentication path. Developers run npx turbo login and npx turbo link from the repository. Vercel-hosted builds need no additional Remote Cache configuration when the Turborepo is linked to Vercel. Other CI providers should define TURBO_TOKEN and TURBO_TEAM, then run normal package scripts such as pnpm build and pnpm test when those scripts call Turborepo. This keeps Remote Caching independent of a specific package manager while preserving the same task graph.

Sources: apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx

Third, monitor the contents and assumptions of cached tasks. Confirm that build outputs exclude tool-internal caches when necessary, that logs do not print secrets, and that environment variables used by tasks are modeled intentionally. Remote Caching is free and available through managed providers or self-hosted caches, but the documentation’s safety guidance is provider-independent: shared artifacts require disciplined task definitions. For next steps, read the caching guide for inputs and outputs, the environment-variable guide for hashing behavior, and CI vendor guides for provider-specific secret setup.

Sources: apps/docs/content/docs/core-concepts/remote-caching.mdx, apps/docs/content/docs/crafting-your-repository/caching.mdx