---
name: cachely-remote-cache
description: Connect an Nx, Lerna, Turborepo, Gradle, or Bazel build to the Cachely remote build cache so tasks are cached once and reused across machines and CI. Use when setting up remote caching, speeding up CI, or sharing a build cache between developers for any of these tools.
---

# Cachely remote cache

Cachely is a hosted remote build cache. Point your build tool at it with a
workspace token and cacheable tasks are stored once and replayed everywhere.

## Prerequisites

1. Create a workspace and generate a token in the dashboard: https://app.cachely.dev
2. Keep the token secret. Provide it to CI as a secret env var; never commit it.

The cache host is `https://remote.cachely.dev`. Each tool speaks its own native
remote-cache protocol - you do not install a Cachely plugin.

## Nx (`/v1/cache`)

Set these environment variables (Nx self-hosted remote cache):

```sh
export NX_SELF_HOSTED_REMOTE_CACHE_SERVER=https://remote.cachely.dev
export NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=<token>
```

Run tasks as usual (`nx build`, `nx affected -t build`). Cache hits are restored
instead of re-executing.

## Turborepo (`/v8/artifacts`)

```sh
export TURBO_API=https://remote.cachely.dev
export TURBO_TOKEN=<token>
export TURBO_TEAM=<any-slug>   # required by turbo; the token identifies the workspace
```

Then `turbo run build`. `TURBO_TEAM` can be any string; Cachely resolves the
workspace from the token, not the slug.

## Gradle (`/v1/gradle`)

In `settings.gradle(.kts)`:

```kotlin
buildCache {
    remote<HttpBuildCache> {
        url = uri("https://remote.cachely.dev")
        isPush = true
        credentials {
            username = ""          // ignored; any value works
            password = "<token>"   // the workspace token
        }
    }
}
```

Gradle's HTTP build cache uses HTTP Basic; Cachely takes the token from the
Basic password. Gradle appends the cache key to the URL itself.

## Bazel (`/v1/bazel`)

In the committed `.bazelrc` (the token goes in a gitignored `user.bazelrc`):

```
build --remote_cache=https://remote.cachely.dev

# Read the cache everywhere, upload from trusted CI only.
build --remote_upload_local_results=false
build:cachely-ci --remote_upload_local_results=true

try-import %workspace%/user.bazelrc
```

```
# user.bazelrc (gitignored - carries the raw token)
build --remote_header="Authorization=Bearer <token>"
```

Bazel uploads locally produced action results by default. Cachely recommends
turning that off until builds are demonstrably hermetic: a non-reproducible
machine that uploads can poison an action result that every other machine then
replays. Trusted CI opts back in per invocation with
`bazel build //... --config=cachely-ci`.

`.bazelrc` options apply in order and the command line overrides them, so the
flag is guidance. The enforcement is the token: give trusted CI a read/write
token (one per pipeline) and give developer machines, pull requests, and forks a
read-only token. Cachely rejects writes from a read-only token with `403` on
both `/ac/` and `/cas/`.

## Notes

- Tokens are scoped to one workspace and subject to that workspace's plan quota.
  When a workspace is over quota, writes are silently skipped and reads miss, so
  builds still succeed - they just re-run the task.
- To authenticate an autonomous agent (rather than a build tool), see the
  `cachely-authentication` skill and https://cachely.dev/auth.md.