Turborepo remote cache setup

export TURBO_API=https://remote.cachely.dev
export TURBO_TOKEN=<your-token>
export TURBO_TEAM=<any-non-empty-value>

The same workspace token works for Nx, Lerna, Turborepo, Gradle, and Bazel. TURBO_TEAM is required by the Turborepo CLI but its value is ignored - the token alone identifies your workspace.

Unlike Nx, turbo does not read .env files for its own settings. If you keep these variables in a gitignored .env.local, load it into each run, for example npx dotenv-cli -e .env.local -- turbo run build. Turbo reads the token only from TURBO_TOKEN: for a read-only setup, put a read-only token in that same variable.

turbo gives each artifact upload 60 seconds. A large artifact on a slow uplink can exceed that, and turbo warns the cache artifact for ... was too large to upload within the timeout and skips the upload. Raise the limit in turbo.json (or with TURBO_REMOTE_CACHE_UPLOAD_TIMEOUT), and check the task's outputs are not capturing caches such as .next/cache:

{
  "remoteCache": { "uploadTimeout": 300 }
}

Run a cacheable task, delete the local cache, then run it again. The second run should report a remote cache hit rather than executing the task:

turbo run build
rm -rf .turbo/cache
turbo run build --summarize

--summarize writes a run summary under .turbo/runs/ recording, per task, whether the result came from the local cache, the remote cache, or a fresh execution. That file is the fastest way to prove the remote cache is actually being consulted.

Turborepo can sign cache artifacts so a tampered payload is rejected on download. Turn it on in turbo.json and supply the key through TURBO_REMOTE_CACHE_SIGNATURE_KEY:

{
  "remoteCache": { "signature": true }
}

The key is yours and never leaves your builds - Cachely stores the signed artifact without being able to forge one. The Turborepo remote cache guide explains the trade-offs in more depth.

Follow the GitHub Actions recipe or choose another provider in CI setup. Choose access based on which builds you trust, as described in tokens and access control.