Remote Caching

Share cache artifacts across your team and CI pipelines.

Benefits

Team members get cache hits from each other's work
CI gets cache hits from local development (and vice versa)
Dramatically faster CI runs after first build
No more "works on my machine" rebuilds

Vercel Remote Cache

Free, zero-config when deploying on Vercel. For local dev and other CI:

Local Development Setup

bash

# Authenticate with Vercel
npx turbo login

# Link repo to your Vercel team
npx turbo link

This creates .turbo/config.json with your team info (gitignored by default).

CI Setup

Set these environment variables:

bash

TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-team-slug>

Get your token from Vercel dashboard → Settings → Tokens.

GitHub Actions example:

yaml

- name: Build
  run: npx turbo build
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Configuration in turbo.json

json

{
  "remoteCache": {
    "enabled": true,
    "signature": false
  }
}

Options:

enabled: toggle remote cache (default: true when authenticated)
signature: require artifact signing (default: false)

Artifact Signing

Verify cache artifacts haven't been tampered with:

bash

# Set a secret key (use same key across all environments)
export TURBO_REMOTE_CACHE_SIGNATURE_KEY="your-secret-key"

Enable in config:

json

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

Signed artifacts can only be restored if the signature matches.

Self-Hosted Options

Community implementations for running your own cache server:

turbo-remote-cache (Node.js) - supports S3, GCS, Azure
turborepo-remote-cache (Go) - lightweight, S3-compatible
ducktape (Rust) - high-performance option

Configure with environment variables:

bash

TURBO_API=https://your-cache-server.com
TURBO_TOKEN=your-auth-token
TURBO_TEAM=your-team

Cache Behavior Control

bash

# Disable remote cache for a run
turbo build --remote-cache-read-only  # read but don't write
turbo build --no-cache                # skip cache entirely

# Environment variable alternative
TURBO_REMOTE_ONLY=true  # only use remote, skip local

Debugging Remote Cache

bash

# Verbose output shows cache operations
turbo build --verbosity=2

# Check if remote cache is configured
turbo config

Look for:

"Remote caching enabled" in output
Upload/download messages during runs
"cache hit, replaying output" with remote cache indicator