How does Nx computation caching work with a remote cache?

Before running a task, Nx computes a hash from everything that could affect its result:

  • the project's source files, filtered by named inputs such as production or default
  • runtime inputs, such as the output of a shell command like node -v
  • environment variable inputs
  • external dependency versions
  • the hashes or outputs of the tasks it depends on

If two machines produce the same hash, Nx treats the task as already done. A cached artifact holds two things: the files declared in the task's outputs and the terminal output it printed. On a hit, Nx restores the files and replays the log, so a hit looks the same as a real run.

A remote cache does not change how hashes are computed. It only gives every machine a shared place to look after the local cache misses.

 CI runner (read-write)              Developer laptop (read-only)
 ----------------------              ----------------------------
 compute task hash                   compute task hash
        |                                   |
 local cache? --hit--> restore       local cache? --hit--> restore
        | miss                              | miss
        v                                   v
 +---------------------- bucket (S3 / GCS) ----------------------+
 |  hit: download -> restore      |  hit: download -> restore    |
 |  miss: run task -> UPLOAD      |  miss: run task, no upload   |
 +---------------------------------------------------------------+

Teams adopt a remote cache because most CI work is repeated. A pull request rebuilds libraries that main built an hour earlier. Parallel jobs re-run the same lint step. A developer who switches branches rebuilds what CI already produced. With a shared cache, each of those becomes a download instead of a full run. That cuts CI minutes and, more noticeably, the time engineers spend waiting for green checks.

+--------------------------- hash inputs ----------------------------+
| sources via named inputs | runtime | env vars | external deps      |
| outputs/hashes of dependency tasks                                 |
+--------------------------------------------------------------------+
         |                                       |
         v                                       v
+------------------+                    +------------------+
| CI runner        |                    | Developer laptop |
| compute hash     |                    | compute hash     |
+------------------+                    +------------------+
         |                                       |
         v                                       v
+------------------+  hit               +------------------+  hit
| local cache      |-----> restore      | local cache      |-----> restore
+------------------+  outputs + log     +------------------+  outputs + log
         | miss                                  | miss
         | (read-write)                          | (read-only)
         v                                       v
+--------------------------------------------------------------------+
|                     remote bucket (S3 or GCS)                      |
|         key = task hash  ->  task outputs + terminal output        |
+--------------------------------------------------------------------+
| CI:     hit -> download + restore | miss -> run task, UPLOAD       |
| Laptop: hit -> download + restore | miss -> run task, no upload    |
+--------------------------------------------------------------------+

Both machines compute the same task hash from the same inputs and check their local cache first. On a local miss they check the shared bucket, and only the read-write CI runner uploads new artifacts.

What are the self-hosted options for an Nx remote cache?

There are four practical ways to give a team a shared cache without Nx Cloud. They differ mainly in who owns the moving parts.

Option What you run Auth and isolation Main cost to the team
Official Nx S3 package An S3 bucket IAM policies on the bucket Bucket policy, lifecycle rules
Official Nx GCS package A GCS bucket IAM roles on the bucket Bucket policy, lifecycle rules
Shared filesystem A network mount that all agents can reach Filesystem permissions Mount reliability, concurrent writes
Custom HTTP server A service that implements the Nx remote cache API Anything you build Uptime, security, API compatibility

The bucket-backed packages are the default choice. Object storage is already durable and access-controlled, so the team only defines who can read and write. A shared filesystem fits when CI agents already share a mount, but network storage adds latency and failure modes to every cache lookup. A custom server gives the most control. You can scope tokens per branch, separate tenants, or log every write. In exchange, the team owns its availability, its security, and keeping up with changes to the API.

Moving off Nx Cloud also removes features that a cache alone does not provide. You lose distributed task execution, run analytics, and managed access scoping. The team either builds replacements or accepts going without them. For many teams, caching is the only feature they use, so the loss doesn't matter.

Package names, licensing terms, and supported Nx versions for these options have changed between releases. Check the current Nx documentation before you commit to one.

How do you set up an Nx S3 cache and a GCS cache?

S3

Create a dedicated bucket in the same region as your CI runners. Same-region placement avoids cross-region transfer charges and keeps restore latency low. A dedicated bucket also keeps the cache's permissions and lifecycle rules from interfering with other data. Don't put static credentials in Nx configuration. The plugin should resolve credentials through the standard AWS credential chain (environment variables, instance or task roles, or OIDC-assumed roles in CI), so the setup works the same on laptops and runners.

Scope the IAM policy to the cache prefix only. Allow s3:GetObject and s3:PutObject on arn:aws:s3:::<bucket>/<prefix>/*, and grant nothing on other buckets. Some plugins also need s3:ListBucket on the bucket ARN, so check the docs before adding it. The accompanying example shows this policy. To use an S3-compatible store such as MinIO, the plugin must support a custom endpoint option. Confirm that in its documentation before you plan around it.

GCS

Use a dedicated bucket in the same region as your runners. Create a service account with object-level roles on that bucket only, not project-wide roles. For example, gcloud storage buckets add-iam-policy-binding gs://<bucket> --member=serviceAccount:<sa-email> --role=roles/storage.objectViewer, plus roles/storage.objectCreator for writers. objectCreator cannot overwrite or delete objects. Confirm the plugin never rewrites existing keys before you rely on it. From CI, authenticate with workload identity federation so jobs get short-lived tokens. That way, no long-lived JSON key can leak through logs or forks.

Plugin configuration

The plugin configuration has the same shape for both clouds: bucket, optional prefix, region, and a read/write toggle. Option names vary between packages and releases, so take them from the current docs.

#!/usr/bin/env bash
set -euo pipefail

# Placeholders: replace with your own values.
BUCKET="acme-nx-cache"
PREFIX="nx"
ROLE="ci-nx-cache-role"            # IAM role assumed by CI via OIDC
GCS_BUCKET="acme-nx-cache-gcs"
SA="nx-cache@acme-ci.iam.gserviceaccount.com"

# --- S3: least-privilege policy scoped to the cache prefix only ---
cat > nx-cache-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "NxCacheObjects",
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::${BUCKET}/${PREFIX}/*"
    }
  ]
}
EOF
# Add s3:ListBucket on arn:aws:s3:::${BUCKET} only if your plugin's docs require it.

aws iam put-role-policy \
  --role-name "$ROLE" \
  --policy-name nx-remote-cache \
  --policy-document file://nx-cache-policy.json

# --- GCS: bucket-scoped object roles, no project-wide grants ---
gcloud storage buckets add-iam-policy-binding "gs://${GCS_BUCKET}" \
  --member="serviceAccount:${SA}" --role="roles/storage.objectViewer"

# Writers only. objectCreator cannot overwrite or delete existing objects.
gcloud storage buckets add-iam-policy-binding "gs://${GCS_BUCKET}" \
  --member="serviceAccount:${SA}" --role="roles/storage.objectCreator"

Grants the CI role get and put access on the S3 cache prefix only, and binds read and create object roles on a single GCS bucket to the cache service account.

Who should get write access, and how do you prevent cache poisoning?

The read/write toggle is the most important setting in that configuration. A remote cache trusts any artifact stored under a hash. Nx computes the hash from inputs, but it does not check that the stored outputs came from those inputs. Anyone holding write credentials can upload a tampered artifact under a valid hash. Every later build that computes that hash will restore it, and that can include a release build. A bucket cache has no per-branch or per-PR isolation, so a write from a feature branch is indistinguishable from a write from main. Nx cannot enforce write scope, so you have to enforce it in IAM.

A workable model:

  • CI on protected branches: read-write. Use a dedicated role whose trust policy is conditioned on the protected ref. On AWS, this means an OIDC trust condition on the token's subject claim that matches the repository and the protected branch. On GCP, it means a Workload Identity Federation attribute condition on the same claims, bound to a service account with object create permission on the cache bucket.
  • Pull request builds, especially from forks: read-only or none. Give them a separate role with object read permission only. If fork PRs can run code you haven't reviewed, give them no cache credentials at all.
  • Developer machines: read-only. Issue these credentials through SSO or short-lived sessions, not long-lived access keys.

The cost of this model is credential sprawl. You maintain one role per environment, and you need to audit periodically that no long-lived write keys have leaked into laptops or CI secrets. You also accept a trade-off. Read-only developers and PR builds never warm the cache, so their hit rate depends on how recently protected-branch CI built the same inputs.

#!/usr/bin/env bash
# Two IAM roles for one Nx cache bucket: write only from main, read for PRs.
set -euo pipefail
OIDC='arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com'
REPO='repo:example-org/monorepo'

# Trust policy: only GitHub OIDC tokens whose subject matches $1 may assume the role.
trust() { cat <<EOF
{"Version":"2012-10-17","Statement":[{"Effect":"Allow",
 "Principal":{"Federated":"$OIDC"},"Action":"sts:AssumeRoleWithWebIdentity",
 "Condition":{"StringEquals":{
  "token.actions.githubusercontent.com:aud":"sts.amazonaws.com",
  "token.actions.githubusercontent.com:sub":"$1"}}}]}
EOF
}

# Permission policy: the S3 actions in $1 on cache objects only.
perms() { cat <<EOF
{"Version":"2012-10-17","Statement":[{"Effect":"Allow",
 "Action":$1,"Resource":"arn:aws:s3:::example-nx-cache/*"}]}
EOF
}

# Read-write role: the subject is pinned to the protected branch, so a feature
# branch or PR job cannot assume it even with the same workflow file.
aws iam create-role --role-name nx-cache-ci-write \
  --assume-role-policy-document "$(trust "$REPO:ref:refs/heads/main")"
aws iam put-role-policy --role-name nx-cache-ci-write --policy-name nx-cache-rw \
  --policy-document "$(perms '["s3:GetObject","s3:PutObject"]')"

# Read-only role for same-repo PR builds. Without PutObject they cannot
# upload an artifact under a valid hash.
aws iam create-role --role-name nx-cache-pr-read \
  --assume-role-policy-document "$(trust "$REPO:pull_request")"
aws iam put-role-policy --role-name nx-cache-pr-read --policy-name nx-cache-ro \
  --policy-document "$(perms '["s3:GetObject"]')"

# Fork PRs get no role and no secrets. Developers use read-only SSO sessions.

This creates an AWS read-write cache role that only GitHub Actions OIDC tokens from the main branch can assume, plus a separate read-only role for pull request builds, so IAM enforces write scope instead of Nx.

How do you handle eviction and retention in the cache bucket?

Retention interacts with that trade-off directly.

Nx writes artifacts to the bucket and never deletes them. Without a rule, the bucket grows with every unique task hash, which is roughly one set per commit per affected project, and storage cost rises steadily.

Both providers expire objects by age at the bucket level. On S3, add a lifecycle rule with an Expiration action set to a number of days. Scope it with a prefix filter if the bucket holds anything besides cache data. If versioning is enabled, add a noncurrent-version expiration as well, or deleted artifacts stay billable as hidden versions. An abort-incomplete-multipart-upload action cleans up interrupted large uploads. On GCS, Object Lifecycle Management uses a Delete action with an age condition in days.

In both cases age is measured from object creation, not last read. A popular artifact still expires on schedule. The next miss rebuilds it and writes it again.

Size the window from your longest-lived branch that still needs cache hits. If release branches live for a six-week cycle and hotfixes land near the end of that cycle, a 14-day window means those hotfix builds start cold. Their base artifacts were created when the branch was cut. In that case, set the window slightly longer than the release cycle, for example 45 days. This is an illustrative estimate, not a recommendation for every repo.

If the window is too short, long-lived branches lose their hit rate. If it is too long, storage grows with little extra benefit.

#!/usr/bin/env bash
# Expire Nx cache artifacts by age. Nx never deletes from the bucket.
# 45 days is an illustrative window: slightly longer than a six-week release cycle.
set -euo pipefail
RETENTION_DAYS=45

# --- S3 ---
cat > s3-lifecycle.json <<EOF
{
  "Rules": [{
    "ID": "expire-nx-cache",
    "Status": "Enabled",
    "Filter": { "Prefix": "nx-cache/" },
    "Expiration": { "Days": ${RETENTION_DAYS} },
    "NoncurrentVersionExpiration": { "NoncurrentDays": 1 },
    "AbortIncompleteMultipartUpload": { "DaysAfterInitiation": 1 }
  }]
}
EOF
# The prefix filter keeps the rule away from non-cache objects in the bucket.
# The noncurrent-version rule only matters if versioning is on.
aws s3api put-bucket-lifecycle-configuration \
  --bucket example-nx-cache \
  --lifecycle-configuration file://s3-lifecycle.json

# --- GCS ---
cat > gcs-lifecycle.json <<EOF
{
  "lifecycle": {
    "rule": [{
      "action": { "type": "Delete" },
      "condition": { "age": ${RETENTION_DAYS}, "matchesPrefix": ["nx-cache/"] }
    }]
  }
}
EOF
# age counts from object creation, not last read, so frequently hit artifacts still expire.
gcloud storage buckets update gs://example-nx-cache \
  --lifecycle-file=gcs-lifecycle.json

Applies equivalent age-based expiration rules, scoped to an nx-cache/ prefix, to an S3 bucket and a GCS bucket, using an illustrative 45-day window.

What does a self-hosted Nx cache cost, and when does it slow builds down?

…every unique hash your repo produces. Even so, storage is rarely the expensive line. The costs that grow are request volume and data transfer, because both scale with how often CI runs, not with how much you keep.

Illustrative estimate (assumed numbers, not a benchmark)

Assumed inputs: 20 MB average compressed artifact, 150 cacheable tasks per pipeline, 200 pipelines per day, 70% hit rate.

  • Cache lookups per day = tasks × pipelines = 150 × 200 = 30,000
  • Downloads (hits) = 30,000 × 0.70 = 21,000 → 21,000 × 20 MB ≈ 420 GB/day
  • Uploads (misses) = 30,000 × 0.30 = 9,000 → 9,000 × 20 MB ≈ 180 GB/day

Over 30 days that is roughly 12.6 TB read. Inside one region this is mostly request charges. If runners are in another region or cloud, the same 12.6 TB is billed as egress, and that line can exceed storage several times over. Multiply your own inputs by your provider's current rates.

Runner placement Transfer billing Fetch latency Risk
Same region, same cloud Usually requests only Low Minimal
Cross-region Inter-region transfer Higher round trips Slow small-task hits
Cross-cloud Internet egress Highest, variable Fetch can lose to rebuild

A hit only helps when fetch time (round trip plus size ÷ throughput) is lower than task runtime. A lint task that takes two seconds gains nothing from a 40 MB download over a distant link. Co-located runners with a high hit rate turn the same request volume into minutes saved per pipeline. Across 200 daily pipelines, that saved time is the return on the bucket.

How do you verify the cache is restoring correct artifacts?

Speed only matters if the restored output is correct. A cache keyed on incomplete inputs returns stale artifacts quickly and without errors. Verification is how you catch that before it reaches a release.

Confirm hits, then force a miss

First, check that CI is actually reading from the bucket. Nx labels cached task output in the terminal, so a remote hit on a fresh runner should show a remote-cache marker, not a local one. If a clean runner reports only local hits or none at all, the remote cache is not configured correctly.

Next, change one input on purpose. Edit a source file, bump a dependency in the lockfile, or set a different value for an environment variable you expect to matter. Rerun the affected task. If it still reports a cache hit, that input is not part of the hash. Running nx show project <name> lets you inspect the resolved inputs for a target.

Audit what the hash can't see

Nx hashes only what you declare. Common gaps:

  • Build-time environment variables such as NODE_ENV.
  • Tool versions such as Node or a compiler.
  • The OS and CPU architecture.

The last gap is the most dangerous with a shared cache. A native module built on an arm64 laptop can be restored onto x86_64 CI runners. A local cache keeps a bad entry like that on one machine. A remote cache serves it to every machine that computes the same hash.

In namedInputs, declare entries such as { "env": "NODE_ENV" } and { "runtime": "node --version" }. Add a runtime entry that prints the platform and architecture, and reference these from each target's inputs. Confirm the exact syntax against the current Nx documentation before you rely on it.

S3 vs GCS: which should you choose, and when should you avoid self-hosting?

Both backends hold Nx cache artifacts equally well. They differ mainly in identity, policy, and logging.

Dimension Amazon S3 Google Cloud Storage
Authentication for CI IAM roles, assumed through an OIDC identity provider for short-lived CI credentials Service accounts, reached through Workload Identity Federation for keyless CI access
Lifecycle tooling Lifecycle rules that expire or transition objects by age, prefix, or tag Object Lifecycle Management rules keyed on age, storage class, and other conditions
Regional placement Buckets live in a single region; cross-region copies require replication Regional, dual-region, or multi-region bucket locations
Access logging and audit Server access logs; CloudTrail data events for per-object API calls Cloud Audit Logs; Data Access logs must be enabled explicitly
Fit with existing infrastructure Natural for runners on EC2, EKS, or AWS-hosted CI Natural for runners on GKE, Compute Engine, or Cloud Build

The feature gaps are small, so the cloud where your CI runners and developers already work usually decides it. That cloud already holds your identity federation and network paths. Placing the bucket there avoids egress charges and cross-cloud latency on every cache hit. It also means you need no second set of credentials to rotate and audit.

Self-hosting fits teams that already run on AWS or GCP and mainly need to share cache artifacts between CI and developer machines. Choose Nx Cloud or another option in these cases:

  • You need more than storage. Distributed task execution, cache analytics, or managed access control are not part of a bucket.
  • You cannot restrict write access to trusted pipelines. A writable bucket open to untrusted branches invites cache poisoning.
  • Your runners and bucket are in different clouds. Every restore pays egress fees and latency, which can wipe out the time the cache saves.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to nx self hosted remote cache, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.