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
turbo build --no-cache                # skip cache entirely

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

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