Configure Turborepo remote caching with Vercel and a self-hosted cache server
domain: turborepo.dev · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Link a Vercel-hosted cache by running npx turbo login in your repo root, then npx turbo link to associate the repository with your Vercel team; Turborepo will store and retrieve artifacts from Vercel's cache automatically
In CI, authenticate without interactive login by setting TURBO_TOKEN to a Vercel API token and TURBO_TEAM to your Vercel team slug; add these as CI secrets and they are picked up automatically
To use a self-hosted cache server, run npx turbo login --manual and supply your custom server's base URL, team name, and API token when prompted; the values are saved to .turbo/config.json
Alternatively, configure the self-hosted cache via environment variables: TURBO_API (base URL), TURBO_TOKEN, and TURBO_TEAM — these override any .turbo/config.json values
Verify caching is active by running npx turbo build --summarize; the task summary will show cache status (HIT or MISS) and the remote cache URL being used
For the self-hosted server, deploy an API-compatible implementation (such as ducktors/turborepo-remote-cache) backed by local disk or an S3-compatible bucket, then point TURBO_API at it
Known gotchas
Turborepo remote caching requires all tasks that should share cache entries to produce deterministic outputs; tasks with volatile outputs (timestamps, random seeds) will always be MISS and pollute the cache with unused artifacts
The self-hosted cache server must implement the Turborepo Remote Caching API specification exactly; deviations cause silent cache misses rather than errors
When TURBO_TOKEN is not set or is invalid, Turborepo falls back silently to local-only caching without warning; always verify remote cache hits in pipeline logs after configuration changes
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?