# 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 Rush](https://cloud.getrush.ai/run/add-remote-caching/turborepo/). Opens 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`

```json
{
  "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.

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

- [Review Pull Requests on a Turborepo Monorepo](https://getrush.ai/run/review-pull-requests/turborepo/)
- [Make Turborepo CI Check Only the Packages a Pull Request Changed](https://getrush.ai/run/run-ci-on-changed-packages/turborepo/)
- [Upgrade npm Dependencies in a Turborepo Monorepo](https://getrush.ai/run/upgrade-npm-dependencies/turborepo/)

## More jobs like this: Review every pull request

- [Add Merged Test Reports to a Playwright Workflow](https://getrush.ai/run/add-report-merging/playwright/)
- [Add SpotBugs to a Gradle Build](https://getrush.ai/run/add-spotbugs/gradle/)
- [Add Spotless Formatting to a Maven Build](https://getrush.ai/run/add-spotless-formatting/maven/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
