A self-hosted Nx cache must authenticate every request, separate read tokens from write tokens, serve over HTTPS and never be run with TLS validation disabled. Nx hands you the API contract but leaves storage, retrieval and authentication to you, so those controls are your job.
What Nx gives you and what it does not
The Nx documentation describes two options: a managed service, or building your own server to an OpenAPI specification. The server manages storage, retrieval and authentication, and may be written in any language as long as it matches the spec. The endpoints transfer tar archives as binary data.
The spec defines two operations: upload a task output, and download one, keyed by task hash. It uses bearer token authentication. Its responses include missing or invalid token, access forbidden (for example a read only token used to write), a conflict when you try to override an existing record, and not found.
Those response codes already describe a sound model: write once per hash, and distinguish read from write permissions.
Checklist
| Control | What to do |
|---|---|
| Authentication | Require the bearer token on every request, both reads and writes |
| Read vs write | Issue read only tokens to developers and PR builds, write tokens to protected CI |
| Immutability | Honor the conflict response: never overwrite an existing hash |
| Transport | HTTPS only, with a certificate trusted by clients |
| Storage | Encrypt at rest, restrict who can read the bucket or disk |
| Retention | Expire old entries, keep a way to wipe the cache quickly |
| Logging | Record writer identity, hash and time |
| Network | Reach the server from build networks only |
The environment variables
Nx uses an environment variable to point at your server and another for its access token. A third is documented as able to turn off TLS certificate validation, by setting it to zero. Do not set it. It disables certificate checks for the whole Node process, not just the cache connection, so a network attacker could impersonate your cache or other services. If your certificate is internal, install your certificate authority in the runner instead.
Token handling
- Create separate tokens for read and write.
- Store write tokens in a secret manager and expose them only to protected branch jobs.
- Rotate on a schedule and after any suspected leak.
- Never print tokens. Nx stores terminal output in cache entries, so a printed token can be saved and replayed.
Recovery plan
Decide before you need it how to wipe the cache. A poisoned entry is keyed by a hash that real builds will compute, so you cannot fix it by waiting. Plan for clearing storage, rotating tokens and rebuilding release artifacts from source.
When to choose managed instead
If you cannot staff the checklist above, a managed service shifts some of it to the provider. Evaluate it with the same questions: who can write, how are tokens scoped, what is the deletion process, and where is data stored.
Quick check
Does Nx verify cache entries against a signature?
The spec describes hash keyed storage and bearer tokens. It does not describe artifact signing, so enforce integrity with your server design and access control.
Is an internal certificate a reason to disable TLS validation?
No. Install your internal certificate authority on the build machines instead.
Sources
Last reviewed: 19 October 2026.
