Remote Cache

Remote caching shares build results across your team and CI so you don't repeat work. You can use Nx Cloud for a fully managed solution or self-host with one of the available plugins.

Self-hosted cache

Great for proof of concepts and small teams.

All packages are free but require an activation key. Getting a key is a fully automated, self-service process that happens during package installation. Install any of the following with nx add:

Package	Storage	Install command
`@nx/s3-cache`	Amazon S3 bucket	`nx add @nx/s3-cache`
`@nx/gcs-cache`	Google Cloud Storage	`nx add @nx/gcs-cache`
`@nx/azure-cache`	Azure Blob Storage	`nx add @nx/azure-cache`
`@nx/shared-fs-cache`	Shared file system directory	`nx add @nx/shared-fs-cache`

The nx add command installs the package, configures your workspace, and walks you through generating an activation key. The key is saved to .nx/key/key.ini and should be committed to your repository. In CI or public repositories, set the NX_KEY environment variable instead.

If you don't have a key yet, run nx register to generate one. If your existing key is expired or invalid, delete .nx/key/key.ini and run nx register again. In CI, verify that the NX_KEY environment variable is set and matches the key in .nx/key/key.ini.

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 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

// Nx 20.8+
{
  "openapi": "3.0.0",
  "info": {
    "title": "Nx custom remote cache specification.",
    "description": "Nx is an AI-first monorepo platform that connects everything from your editor to CI. Helping you deliver fast, without breaking things.",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/cache/{hash}": {
      "put": {
        "description": "Upload a task output",
        "operationId": "put",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully uploaded the output"
          },
          "401": {
            "description": "Missing or invalid authentication token.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "403": {
            "description": "Access forbidden. (e.g. read-only token used to write)",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "409": {
            "description": "Cannot override an existing record"
          }
        },
        "parameters": [
          {
            "in": "header",
            "description": "The file size in bytes",
            "required": true,
            "schema": {
              "type": "number"
            },
            "name": "Content-Length"
          },
          {
            "name": "hash",
            "description": "The task hash corresponding to the uploaded task output",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        }
      },
      "get": {
        "description": "Download a task output",
        "operationId": "get",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved cache artifact",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "An octet stream with the content."
                }
              }
            }
          },
          "403": {
            "description": "Access forbidden",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "Error message provided to the Nx CLI user"
                }
              }
            }
          },
          "404": {
            "description": "The record was not found"
          }
        },
        "parameters": [
          {
            "name": "hash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "description": "Auth mechanism",
        "scheme": "bearer"
      }
    }
  }
}

Usage 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 to 0 to disable TLS certificate validation.

Migrating from custom tasks runners

You might have used Nx 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.

Looking for conformance or code owners?

If you previously used Nx Powerpack for conformance rules or code ownership, those features are now part of Nx Enterprise. See:

Conformance — write and enforce language-agnostic rules across your workspace
Owners — define code ownership at the project level and auto-generate CODEOWNERS files