How do I set up a self-hosted Nx remote cache without managing the infrastructure myself?

Nx supports pointing its remote cache at any server that speaks the self-hosted cache API - one environment variable and your whole team shares build results. The catch is the second half of that sentence: "any server" means someone has to run that server. This post walks through what a self-hosted Nx remote cache actually requires, what the DIY options cost you in practice, and how to get the self-hosted model - your endpoint, your tokens, your data boundaries - without standing up or babysitting the infrastructure yourself.

What "self-hosted remote cache" means in Nx

Every cacheable Nx task produces an artifact: the task's outputs plus its terminal output, addressed by a hash of its inputs. A remote cache is just a place to store and retrieve those artifacts over HTTP so a task computed once - on a colleague's laptop or in CI - never runs again anywhere else.

Since Nx 21, the officially supported way to bring your own cache server is the self-hosted remote cache API: an OpenAPI-specified contract with two essential endpoints (GET /v1/cache/:hash and PUT /v1/cache/:hash) authenticated with a bearer token. Configuration is two environment variables:

NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://your-cache-endpoint
NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=<token>

That is the whole client-side story. Nx does the hashing, the uploading, and the downloading. The open question - and the reason many teams stall here - is what sits on the other end of that URL.

The DIY route, and what it really costs

Teams that do not want a SaaS cache typically reach for one of two options: an S3-compatible bucket behind a community cache plugin, or a small custom server that implements the API against object storage. Both work on day one. The costs show up on day thirty:

• Storage lifecycle. Build artifacts accumulate fast - a busy monorepo can produce gigabytes per week. Without retention rules the bucket grows forever; with naive retention you evict artifacts your team still needs and take rebuild storms.
• Token management. One shared token in a CI secret is easy. Per-developer tokens, revoking a leaked token, rotating tokens when someone leaves - that is an auth system, and now you are maintaining one.
• Write access is a supply-chain surface. Anyone who can write to the cache can plant a poisoned artifact that every other machine will happily replay. This is exactly the class of attack behind CVE-2025-36852 (CREEP). A safe setup needs read-only tokens for untrusted contexts and immutable artifacts - both are things you must build, not defaults you get.
• Availability and latency. If the cache is down or slow, every build in the company feels it. A cache server needs monitoring, a health endpoint, and ideally an edge presence so a laptop in one region is not pulling artifacts across an ocean.
• Zero observability. A bucket cannot tell you your hit rate, which targets miss and why, or how much compute the cache actually saved. Without that, you cannot tune your cache inputs or justify the setup to anyone.

None of these is hard in isolation. Together they turn "point Nx at a bucket" into a part-time platform-engineering job that nobody was hired to do.

The middle path: self-hosted protocol, managed infrastructure

Here is the useful realization: NX_SELF_HOSTED_REMOTE_CACHE_SERVER does not care who operates the server. The self-hosted API is an open contract, which means a managed service can implement it and you keep everything that made self-hosting attractive - a standard protocol, no vendor lock-in on the client, your own tokens and endpoint - while someone else owns the storage, the auth, the retention, and the uptime.

That is exactly what Cachely is: a managed implementation of the Nx self-hosted cache API. The setup is the same two variables:

NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://remote.cachely.dev
NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=<your workspace token>

And the operational checklist from the previous section is already handled:

• Storage and retention - artifacts live in managed object storage with automatic expiry, so the cache never grows unbounded and you never write a lifecycle policy.
• Tokens with names and scopes - mint a token per developer, per repo, or per CI pipeline from the dashboard, label it, and revoke it independently. Read-only tokens for PR builds from untrusted branches close the cache-poisoning hole by design.
• Edge delivery - the cache runs on a global edge network, so artifact reads are fast from CI in one region and laptops in another, with no servers for you to place or scale.
• Insights included - hit rates, time saved, per-target and per-project breakdowns, so you can see what the cache is doing and tune what it is not.

Step by step

The full setup, end to end:

• Sign in to the dashboard and create a workspace for your repo.
• Create an access token (a read-write one for trusted CI and local dev; read-only for anything untrusted).
• Export the two NX_SELF_HOSTED_REMOTE_CACHE_* variables locally (an .env.local works - Nx loads it automatically) and add them as secrets in CI.
• Run any cacheable task twice: the first run executes and uploads, the second prints [remote cache] and completes in milliseconds.

There is no agent to install, no plugin to add to your workspace, and no change to any project configuration. If you ever want to leave, unset two environment variables.

When actually running your own server is the right call

Managed is not the answer for everyone. If you are under a strict data-residency regime where build artifacts cannot leave your network, or you already have a platform team operating object storage with auth, quotas, and monitoring as their day job, running your own implementation of the API is reasonable - the protocol is open precisely so you can.

For everyone else, the honest comparison is not "free bucket vs. paid service". It is engineer-hours spent building and running cache infrastructure vs. a setup that takes five minutes and is usually repaid within the first week.