Configure Nx Remote Cache

Last updated: September 21, 2026

What is Nx Remote Cache

Nx is a Monorepo build system with Remote Caching support that speeds up builds by caching task outputs and reusing them across different machines.

Nx includes support for TypeScript & JavaScript frontend, backend, Electron & React Native applications in Monorepo or multi-repo setups.

Notable plugins: @nx/react, @nx/angular, @nx/vue, @nx/node, Bun, @nx/react-native, @bennymeg/nx-electron.

Nx main concepts are Targets & Tasks, for each target Nx computes a hash of the task definition, inputs, environment, and relevant configuration, then checks Local and Remote Cache before running the work locally.

On a Cache Miss Nx runs the task, stores the outputs, and makes them available for later builds.
On a Cache Hit Nx quickly restores the outputs and skips the expensive work across the build graph.

BuildFetch Cache fully implements the Nx Remote Cache Specification both in Cloud & On-Prem. Nx builds can use BuildFetch as their shared Remote Cache for CI, Engineer & AI agent environments without 3rd party adapters.

Official Nx docs: "How Caching Works".

Schematic example: say a first run of nx build web misses the cache, spends time executing the tasks, and uploads the results to Nx Remote Cache:

Schematic Example of Nx Cache Miss

nx build web

  Inputs
  +----------------------+
  | source files         |
  | project config       |
  | task options         |
  | env vars             |
  | ...                  |
  +----------+-----------+
             |
             v
  Compute cache keys from inputs
             |
             v
  +----------------------+
  | Nx Remote Cache      |
  | keys: a3f9...c2      |
  | status: MISS         |
  +----------+-----------+
             |
             v
  Run tasks (~10 minutes)
             |
             v
  Upload task outputs to Remote Cache

Later builds with the same or partially same inputs reuse all or most of those entries. Nx computes the cache keys, hits remote cache, and restores the outputs in seconds instead of rebuilding.

Schematic Example of Nx Cache Hit

nx build web  (same inputs on another machine)

  Inputs unchanged
  source files · project config · task options · env vars
             |
             v
  Same cache key: a3f9...c2
             |
             v
  +----------------------+
  | Nx Remote Cache      |
  | key: a3f9...c2       |
  | status: HIT          |
  +----------+-----------+
             |
             v
  Downloads outputs from Remote Cache (~ few seconds)
             |
             v
  Skip ~10 minutes task run
  Build finishes much quicker.

For Nx outputs to be shared across machines, Nx needs to be configured with Remote Cache.

Nx Remote Caching lets teams share build outputs across engineer workstations, CI, and AI agent environments.

CI, having a more reproducible and controlled environment, typically both reads from and writes to the shared remote cache. Engineers and AI agents read those outputs without uploading new entries.

That keeps the cache warm from reproducible CI builds while reducing repeated work on other machines.

Nx reuses an output only when the task inputs and relevant configuration match. Keep project configuration, dependency graphs, environment variables, and build tool versions consistent when sharing a cache.

Instead of rerunning the same tasks on every machine, Nx restores cached outputs, which turns builds that took minutes into cached builds that finish in seconds when hit rates are high.

Cached Nx Build Example

After CI populates the Nx Remote Cache, a clean rebuild on another machine can resolve many expensive tasks from cache. In a typical scenario:

First build, where CI populates the remote cache:

Schematic Example of Cold Build

$ export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://cache.region.buildfetch.com/project-id/nxcache"
$ export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-token>"
$ nx build web

> NX  Running target build for project web
... compiling ...
Build completed in 10m 4s

Subsequent build, whether by an engineer, AI agent, or fresh CI agent, can finish in seconds:

Schematic Example of Warm Build

$ export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://cache.region.buildfetch.com/project-id/nxcache"
$ export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-token>"
$ nx build web

> NX  Retrieved outputs from remote cache
Build completed in 4s

Configure Nx Remote Cache

Before setting up Nx Remote Cache, ensure you have created BuildFetch Project and Token(s). Official Nx self-hosted caching documentation: https://nx.dev/docs/guides/tasks--caching/self-hosted-caching#usage-notes.

Nx Remote Cache is configured with environment variables.

BuildFetch Project Cache Setup tab will provide:

NX_SELF_HOSTED_REMOTE_CACHE_SERVER
NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN

Cache Access

Use a cache:readonly Token by default on developer and AI agent machines. Trusted environments like CI should use a cache:readwrite Token and explicitly enable uploads.

For Token management, rotation, and Open Source guidance, see Set up BuildFetch Cache Project.

Nx uses the BuildFetch Token as the write boundary; the client configuration is otherwise unchanged.

Read-only

Bash

export NX_SELF_HOSTED_REMOTE_CACHE_SERVER="https://cache.region.buildfetch.com/project-id/nxcache"
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-readonly-token>"

Read-write

Bash

export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN="<generated-readwrite-token>"

Export these variables in the shell or CI environment used for compilation, then simply run your build through Nx. Nx logs will confirm whether the cache is active:

Nx Cache Check

# Build with read-write setup to upload caches to BuildFetch.
$ nx build web
# Clean local Nx caches.
$ nx reset
# Download caches from BuildFetch skipping expensive work. 
$ nx build web