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

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

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

Get your token from Vercel dashboard → Settings → Tokens.

GitHub Actions example:

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

Configuration in turbo.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:

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

Enable in config:

{
  "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:

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

Cache Behavior Control

# Disable remote cache for a run
turbo build --remote-cache-read-only  # read but don't write; deprecated, use --cache=local:rw,remote:r
turbo build --no-cache                # skip cache writes (reads still hit); deprecated, use --cache=local:r,remote:r

# Environment variable alternative
TURBO_CACHE=remote:rw  # only use remote, skip local (TURBO_REMOTE_ONLY is deprecated)

Debugging Remote Cache

# 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