Remote Cache
There are several ways to set up remote caching with Nx.
Recommended for everyone.
You'll also get access to advanced CI features:
Recommended for large organizations.
Includes everything from Nx Cloud, plus:
- Work hand-in-hand with the Nx team for continual improvement
- Run on the Nx Cloud servers in any region or run fully self-contained, on-prem
- SOC 2 type 1 and 2 compliant and comes with single-tenant, dedicated EU region hosting as well as on-premise
Self-Hosted Cache
Great for proof of concepts and small teams.
CREEP (CVE-2025-36852) is a critical vulnerability in bucket-based self-hosted remote caches that allows anyone with PR access to poison production builds. Many organizations are unaware of this security risk. Learn more
All packages below (along with other bucket-based remote cache implementations) are listed in the CVE and are not allowed in many organizations.
All packages are free but require an activation key. Getting a key is a fully automated, self-service process that happens during package installation.
The following remote cache adapters are available:
- @nx/s3-cache: Cache is self-hosted on an Amazon S3 bucket
- @nx/gcs-cache: Cache is self-hosted on Google Cloud storage
- @nx/azure-cache: Cache is self-hosted on Azure
- @nx/shared-fs-cache: Cache is self-hosted on a shared file system location
Why require an activation key? It simply helps us know and support our users. If you prefer not to provide this information, you can also build your own cache server.
Build Your Own Caching Server
Starting in Nx version 20.8, you can build your own caching server using the OpenAPI specification below. This allows you to create a custom remote cache server tailored to your specific needs. The server manages all aspects of the remote cache, including storage, retrieval, and authentication.
Implementation is up to you, but the server must adhere to the OpenAPI specification below to ensure compatibility with Nx's caching mechanism. The endpoints transfer tar archives as binary data. Note that while the underlying data format may change in future Nx versions, the OpenAPI specification should remain stable.
You can implement your server in any programming language or framework, as long as it adheres to the OpenAPI spec.
Open API Specification
1{
2 "openapi": "3.0.0",
3 "info": {
4 "title": "Nx custom remote cache specification.",
5 "description": "Nx is an AI-first build platform that connects everything from your editor to CI. Helping you deliver fast, without breaking things.",
6 "version": "1.0.0"
7 },
8 "paths": {
9 "/v1/cache/{hash}": {
10 "put": {
11 "description": "Upload a task output",
12 "operationId": "put",
13 "security": [
14 {
15 "bearerToken": []
16 }
17 ],
18 "responses": {
19 "202": {
20 "description": "Successfully uploaded the output"
21 },
22 "401": {
23 "description": "Missing or invalid authentication token.",
24 "content": {
25 "text/plain": {
26 "schema": {
27 "type": "string",
28 "description": "Error message provided to the Nx CLI user"
29 }
30 }
31 }
32 },
33 "403": {
34 "description": "Access forbidden. (e.g. read-only token used to write)",
35 "content": {
36 "text/plain": {
37 "schema": {
38 "type": "string",
39 "description": "Error message provided to the Nx CLI user"
40 }
41 }
42 }
43 },
44 "409": {
45 "description": "Cannot override an existing record"
46 }
47 },
48 "parameters": [
49 {
50 "in": "header",
51 "description": "The file size in bytes",
52 "required": true,
53 "schema": {
54 "type": "number"
55 },
56 "name": "Content-Length"
57 },
58 {
59 "name": "hash",
60 "description": "The task hash corresponding to the uploaded task output",
61 "in": "path",
62 "required": true,
63 "schema": {
64 "type": "string"
65 }
66 }
67 ],
68 "requestBody": {
69 "content": {
70 "application/octet-stream": {
71 "schema": {
72 "type": "string",
73 "format": "binary"
74 }
75 }
76 }
77 }
78 },
79 "get": {
80 "description": "Download a task output",
81 "operationId": "get",
82 "security": [
83 {
84 "bearerToken": []
85 }
86 ],
87 "responses": {
88 "200": {
89 "description": "Successfully retrieved cache artifact",
90 "content": {
91 "application/octet-stream": {
92 "schema": {
93 "type": "string",
94 "format": "binary",
95 "description": "An octet stream with the content."
96 }
97 }
98 }
99 },
100 "403": {
101 "description": "Access forbidden",
102 "content": {
103 "text/plain": {
104 "schema": {
105 "type": "string",
106 "description": "Error message provided to the Nx CLI user"
107 }
108 }
109 }
110 },
111 "404": {
112 "description": "The record was not found"
113 }
114 },
115 "parameters": [
116 {
117 "name": "hash",
118 "in": "path",
119 "required": true,
120 "schema": {
121 "type": "string"
122 }
123 }
124 ]
125 }
126 }
127 },
128 "components": {
129 "securitySchemes": {
130 "bearerToken": {
131 "type": "http",
132 "description": "Auth mechanism",
133 "scheme": "bearer"
134 }
135 }
136 }
137}
138Usage Notes
To use your custom caching server, set the NX_SELF_HOSTED_REMOTE_CACHE_SERVER environment variable. The following environment variables also affect behavior:
NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN: The authentication token to access the cache server.NODE_TLS_REJECT_UNAUTHORIZED: Set to0to disable TLS certificate validation.
Migrating From Custom Tasks Runners
You might have used Nx's now-deprecated custom task runners API in these scenarios:
- To implement custom self-hosted caching: use one of the implementations listed above
- To inject custom behavior before and after running tasks: use our new API with dedicated pre and post hooks
To learn more about migrating from custom task runners, please refer to this detailed guide.