All jobs

Add Remote Caching to a Turborepo Monorepo

Yes. An agent turns on signed remote caching in turbo.json, writes a CI workflow that reads the token from secrets, proves cold remote hits, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the task graph before it touches the cache, because a remote cache only pays off for tasks whose inputs and outputs are declared right. In a monorepo laid out like the basic example in vercel/turborepo, turbo.json declares four tasks: build depends on ^build, lists inputs as $TURBO_DEFAULT$ plus .env*, and keeps .next/** as outputs while excluding .next/cache/** and .next/dev/**; lint and check-types depend on their ^ counterparts; dev is cache: false and persistent. The root package.json pins turbo 2.10.12 and pnpm 11.25 as packageManager, and the workspace holds two Next.js apps, web and docs, and three packages. .gitignore already lists .turbo. There is no .github/workflows directory, so every CI build today would start cold.

The configuration change is two keys. remoteCache goes into turbo.json with signature: true, so every artifact is signed with TURBO_REMOTE_CACHE_SIGNATURE_KEY and a tampered one is refused on download, and enabled: true stated rather than assumed. The agent does not run turbo login or turbo link, which write a person's token to their home directory; CI gets its identity from environment variables instead. The workflow it writes, .github/workflows/ci.yml, checks out, installs pnpm from the packageManager field, runs pnpm install --frozen-lockfile, and then pnpm turbo run build lint check-types with TURBO_TOKEN, TURBO_TEAM and the signature key read from repository secrets, and TURBO_API set only when the team runs its own cache server.

Two things come from reading rather than from the docs. The inputs of build include .env*, so a developer's local .env changes the hash and a cold CI run with no .env will never hit an artifact a laptop uploaded; the workflow therefore sets no env file and the pull request says the cache is shared between CI runs first, and with laptops only for tasks whose inputs match. And check-types in apps/web runs next typegen before tsc, which writes files, so the agent adds an outputs entry for that task so a cache hit restores what the next step expects.

Proof needs a cache server the agent controls, so in its sandbox it starts the open-source turborepo-remote-cache on localhost with a throwaway token, exports TURBO_API, TURBO_TOKEN and TURBO_TEAM, runs pnpm turbo run build --summarize once to fill it, then deletes .turbo and every .next directory and runs again. The second summary shows each build task as a cache hit with remote as the source, which the agent quotes with the time saved, then runs a third time after editing one line in packages/ui to show only the two apps rebuild and docs and web are misses while ui is a hit downstream of nothing. The server is stopped and nothing from it is committed.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add remote caching to this Turborepo monorepo. Read turbo.json, package.json, pnpm-workspace.yaml, .gitignore, apps/web/package.json, apps/docs/package.json and the packages' package.json files first. Add a remoteCache block to turbo.json with signature true and enabled true; do not run turbo login or turbo link. Add outputs for any task that writes files before tsc. Write .github/workflows/ci.yml that installs pnpm from the packageManager field, runs pnpm install --frozen-lockfile, and runs turbo run build lint check-types with TURBO_TOKEN, TURBO_TEAM and TURBO_REMOTE_CACHE_SIGNATURE_KEY from secrets and TURBO_API when set. Prove it: start turborepo-remote-cache locally with a throwaway token, run the build with --summarize to fill it, delete .turbo and every .next directory, run again and quote the remote hits and time saved, then change one line in packages/ui and run a third time to show what rebuilds. Open a pull request with the three summaries and the secrets the team must add.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with turbo.json changed in two places, one new workflow file, and nothing else. The description quotes three --summarize runs against the local cache server: the first all misses, the second with every build a remote hit and the wall-clock difference, the third after a one-line change in packages/ui with the hits and misses it caused. It lists the three secrets to add to the repository and says which is optional.

The description also explains the .env* input in plain words, so nobody expects a laptop build to be a hit in CI, and why signature: true is on from the first day rather than added later when the cache is already full of unsigned artifacts.

Before merging, a reviewer chooses the cache: Vercel's, with TURBO_TEAM set to the team slug and a token from the dashboard, or a self-hosted server with TURBO_API pointing at it. The workflow runs the same either way, and the pull request is written so that only the secrets differ.

Run it on every pull request

Once the cache is on, the thing to keep is that tasks stay cacheable. An automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and a prompt that reads turbo.json and the diff starts a run per push: a new script in a package with no task entry, an output directory a task writes but does not declare, or an environment variable read in a build with no env entry gets a review comment on that line with the fix, since each of those turns a hit into a stale result or a miss.

Only work by an owner, member or collaborator fires the trigger; a pull request from a fork never does. Each run installs that pull request's branch in its own sandbox, so a review never reads another branch's .turbo directory.

The use case this job follows, with its automation and trigger: Review every pull request.

Why run it on Rush?

Remote caching is a configuration change that is easy to turn on and hard to know is working, because a miss looks like a normal build. The questions that matter are which inputs are in the hash, which outputs are restored, and whether a cold machine actually hits. In a Rush sandbox the agent reads the task graph, runs a cache server it can inspect, and shows a cold checkout hitting it before the team adds a single secret.

The record of the run keeps all three summaries, and the pull request quotes them, so the reviewer sees what rebuilds after a change to a shared package rather than taking the cache on faith. Across every monorepo a team runs, the same request runs in parallel, one sandbox and one pull request each.

Frequently asked questions

Does the agent need a Vercel account?

No. It proves the change against a local turborepo-remote-cache server with a throwaway token, started in its sandbox and stopped after. The workflow reads TURBO_TOKEN, TURBO_TEAM and TURBO_API from secrets, so the team points it at Vercel's cache or its own server by adding those, not by changing the pull request.

Why is signature verification on from the start?

Because a cache is a build input: an artifact anyone with the token can upload is restored into your deploy. With signature true, every artifact is signed with TURBO_REMOTE_CACHE_SIGNATURE_KEY and a mismatch is refused. Turning it on later would leave the unsigned artifacts already uploaded unusable, so day one is the cheap time.

Will my laptop's builds be cache hits in CI?

Only when the inputs match. The build task lists .env* among its inputs, so a local .env puts a different hash on the laptop's artifact than CI computes with none. The pull request says so, and the first gain is between CI runs, where the inputs are the same.

What does the third summary show?

After one line changes in packages/ui, the run shows ui as a miss and both apps rebuilding because they depend on it through ^build, while lint and check-types for unrelated packages stay hits. That is the dependency graph doing what turbo.json declares, visible in one run.

More Turborepo jobs

More jobs like this: Review every pull request

Keep reading