1# Remote Caching
2 
3Share cache artifacts across your team and CI pipelines.
4 
5## Benefits
6 
7- Team members get cache hits from each other's work
8- CI gets cache hits from local development (and vice versa)
9- Dramatically faster CI runs after first build
10- No more "works on my machine" rebuilds
11 
12## Vercel Remote Cache
13 
14Free, zero-config when deploying on Vercel. For local dev and other CI:
15 
16### Local Development Setup
17 
18```bash
19# Authenticate with Vercel
20npx turbo login
21 
22# Link repo to your Vercel team
23npx turbo link
24```
25 
26This creates `.turbo/config.json` with your team info (gitignored by default).
27 
28### CI Setup
29 
30Set these environment variables:
31 
32```bash
33TURBO_TOKEN=<your-token>
34TURBO_TEAM=<your-team-slug>
35```
36 
37Get your token from Vercel dashboard → Settings → Tokens.
38 
39**GitHub Actions example:**
40 
41```yaml
42- name: Build
43  run: npx turbo build
44  env:
45    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
46    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
47```
48 
49## Configuration in turbo.json
50 
51```json
52{
53  "remoteCache": {
54    "enabled": true,
55    "signature": false
56  }
57}
58```
59 
60Options:
61 
62- `enabled`: toggle remote cache (default: true when authenticated)
63- `signature`: require artifact signing (default: false)
64 
65## Artifact Signing
66 
67Verify cache artifacts haven't been tampered with:
68 
69```bash
70# Set a secret key (use same key across all environments)
71export TURBO_REMOTE_CACHE_SIGNATURE_KEY="your-secret-key"
72```
73 
74Enable in config:
75 
76```json
77{
78  "remoteCache": {
79    "signature": true
80  }
81}
82```
83 
84Signed artifacts can only be restored if the signature matches.
85 
86## Self-Hosted Options
87 
88Community implementations for running your own cache server:
89 
90- **turbo-remote-cache** (Node.js) - supports S3, GCS, Azure
91- **turborepo-remote-cache** (Go) - lightweight, S3-compatible
92- **ducktape** (Rust) - high-performance option
93 
94Configure with environment variables:
95 
96```bash
97TURBO_API=https://your-cache-server.com
98TURBO_TOKEN=your-auth-token
99TURBO_TEAM=your-team
100```
101 
102## Cache Behavior Control
103 
104```bash
105# Disable remote cache for a run
106turbo build --remote-cache-read-only  # read but don't write
107turbo build --no-cache                # skip cache entirely
108 
109# Environment variable alternative
110TURBO_REMOTE_ONLY=true  # only use remote, skip local
111```
112 
113## Debugging Remote Cache
114 
115```bash
116# Verbose output shows cache operations
117turbo build --verbosity=2
118 
119# Check if remote cache is configured
120turbo config
121```
122 
123Look for:
124 
125- "Remote caching enabled" in output
126- Upload/download messages during runs
127- "cache hit, replaying output" with remote cache indicator
128