Turborepo Remote Cache

Search the Marketplace for Turborepo Remote Cache on Ubuntu 24.04 and choose your VM size. Attach an NSG that allows TCP 22 (SSH) from your management network, and TCP 80 (the cache API and health endpoint) from the developer and CI machines that use the cache.

Bearer token authentication protects the artifact API, so you can expose the cache to your build fleet. Still restrict the source ranges to networks you control.

RG="turborepo-cache-prod"; LOCATION="eastus"; VM_NAME="turbo-cache-01" IMAGE_URN="sac1647283583153:turborepo-remote-cache-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name turbo-vnet --address-prefix 10.90.0.0/16 --subnet-name turbo-subnet --subnet-prefix 10.90.1.0/24 az network nsg create -g "$RG" --name turbo-nsg az network nsg rule create -g "$RG" --nsg-name turbo-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name turbo-nsg --name allow-cache --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:turborepo-remote-cache-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name turbo-vnet --subnet turbo-subnet --nsg turbo-nsg --public-ip-sku Standard

ssh azureuser@<vm-ip>

The Node app serves the cache on 127.0.0.1:3000, and nginx fronts it on :80. The public health endpoint returns 200 with no authentication. The connectivity status probe reports the cache as enabled. Neither exposes any cache data.

sudo systemctl is-active turborepo-remote-cache nginx ss -tln | grep -E ':80|:3000' echo "public health / -> HTTP $(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1/)" curl -s http://127.0.0.1/v8/artifacts/status

Both services are active, nginx listens on :80 and the app on 127.0.0.1:3000, the public health endpoint returns HTTP 200, and the status probe returns {"status":"enabled",...}.

The bearer token was generated on this VM's first boot and stored in a root-only file. Read it and keep it secret. Then confirm that a request to the artifact API without a token is rejected, and that the per-VM token authenticates.

sudo cat /root/turborepo-remote-cache-info.txt
T=$(sudo grep '^TURBO_TOKEN=' /root/turborepo-remote-cache-info.txt | cut -d= -f2-)
H=$(head -c 64 /dev/urandom | sha256sum | awk '{print $1}')
echo "no token -> HTTP $(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1/v8/artifacts/$H?teamId=sac")"
echo "wrong token -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -H 'Authorization: Bearer wrongtoken' "http://127.0.0.1/v8/artifacts/$H?teamId=sac")"
echo "per VM token-> HTTP $(curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $T" "http://127.0.0.1/v8/artifacts/$H?teamId=sac")"

The info note holds TURBO_TOKEN, the cache URL and the team. It is owned by root:root with mode 0600.

A request with no Authorization header returns 400, and a wrong token returns 401. The per-VM token returns 404 for this random unknown hash. That is the authenticated "not cached yet" response. The cache never serves artifacts without the token.

Turborepo uploads each task's output to the cache, keyed by a hash, and downloads it on the next build. Store a blob with an authenticated PUT, then fetch it back and confirm that it matches byte for byte. Turborepo does exactly this for every cached task.

T=$(sudo grep '^TURBO_TOKEN=' /root/turborepo-remote-cache-info.txt | cut -d= -f2-) BLOB="hello from turborepo remote cache at $(date -u +%FT%TZ)"
HASH=$(printf '%s' "$BLOB" | sha256sum | awk '{print $1}') printf '%s' "$BLOB" | curl -s -H "Authorization: Bearer $T" -H 'Content-Type: application/octet-stream' \
  -X PUT --data-binary @- "http://127.0.0.1/v8/artifacts/$HASH?teamId=sac" -o /dev/null -w 'PUT /v8/artifacts -> HTTP %{http_code}\n'
GOT=$(curl -s -H "Authorization: Bearer $T" "http://127.0.0.1/v8/artifacts/$HASH?teamId=sac") [ "$GOT" = "$BLOB" ] && echo "GET /v8/artifacts -> byte for byte match" || echo "GET /v8/artifacts -> MISMATCH" echo "unauthenticated GET -> HTTP $(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1/v8/artifacts/$HASH?teamId=sac")"

The PUT returns 200, and the authenticated GET returns the identical blob. An unauthenticated GET of the same key returns 400, so cached content is never served without the token.

In your monorepo, point Turborepo at this server with three environment variables, using the token from Step 5. Turborepo reads TURBO_API, TURBO_TOKEN and TURBO_TEAM, and sends every task result to the cache:

# In your monorepo, before running turbo (token from /root/turborepo-remote-cache-info.txt)
export TURBO_API="http://<vm-ip>"
export TURBO_TOKEN="<turbo-token>"
export TURBO_TEAM="sac"
# Now run any build; results are pushed to and pulled from the remote cache turbo build

Alternatively, add the cache to your project's turbo.json remote cache settings, or pass --api, --token and --team on the turbo command line.

Run any build twice. The first build populates the cache, and a clean second build pulls the results from the cache instead of recomputing them. Share the same cache across your CI fleet so that every machine benefits.

The cache is stored on the local filesystem under /var/lib/turborepo-remote-cache/cache on the OS disk. Inspect the configuration and disk usage:

cat /etc/turborepo-remote-cache/turbo-cache.env du -sh /var/lib/turborepo-remote-cache/cache 2>/dev/null df -h /var/lib/turborepo-remote-cache

Tunables live in /etc/turborepo-remote-cache/turbo-cache.env. The maximum artifact size is BODY_LIMIT, and storage is the local provider at STORAGE_PATH.

To grow the cache, attach a dedicated data disk and mount it at /var/lib/turborepo-remote-cache/cache, preserving turbo ownership. Then run sudo systemctl restart turborepo-remote-cache. The local provider does not evict automatically, so prune or rotate the cache directory periodically.

Bearer token authentication protects the token over the wire only if the transport is encrypted. Restrict the NSG source ranges to networks you control. For traffic across untrusted networks, terminate TLS at the nginx front. Add a certificate and a listen 443 ssl; server block to nginx, or place the VM behind an Azure Application Gateway or Load Balancer that terminates HTTPS:

# Terminate TLS at the nginx front (see /etc/nginx/sites-available/turborepo-remote-cache)
# listen 443 ssl;
# ssl_certificate /etc/nginx/tls/cert.pem;
# ssl_certificate_key /etc/nginx/tls/key.pem;
# then set TURBO_API=https://<vm-ip> on your clients echo "Terminate HTTPS at nginx or an Azure Application Gateway, then use https:// on clients."

With TLS enabled, set TURBO_API=https://<vm-ip> on your clients so the token is always sent over an encrypted channel.

Find Turborepo Remote Cache on AWS Marketplace, published by SecureAnyCloud. Choose Continue to Subscribe, then Continue to Configuration, then Continue to Launch.

Select the Ubuntu 24.04 delivery option, your instance type (m5.large) and your key pair. Choose a security group that allows TCP 22 for administration and TCP 80 from the client networks that use the cache.

Connect over SSH with your EC2 key pair, as the login user for the OS variant you launched.

OS variant SSH login user Example

Ubuntu 24.04 ubuntu ssh -i your-key.pem ubuntu@<public-ip>

ssh -i your-key.pem ubuntu@<public-ip>

On first boot, the image resolves the instance public IP through EC2 instance metadata (IMDSv2), creates a per-instance bearer token and writes the fail-secure bootstrap marker. Then systemd starts the cache server. This takes less than a minute.

Confirm that both services are active, and that the cache server is bound to loopback only while nginx serves the network:

sudo systemctl start turborepo-remote-cache.service nginx.service 2>/dev/null || true sleep 2
sudo systemctl is-active turborepo-remote-cache.service nginx.service
sudo ss -tln | grep -E ':(80|3000) '

The cache and nginx services report active. The cache server listens on 127.0.0.1:3000 (loopback only), and nginx listens on port 80.

nginx handles the unauthenticated health endpoint entirely, with no cache round trip. This makes it a good load-balancer health check:

curl -s http://127.0.0.1/
curl -s -o /dev/null -w 'health: HTTP %{http_code}\n' http://127.0.0.1/

The per-instance bearer token lives in a root-only file. Read it over SSH:

sudo cat /root/turborepo-remote-cache-info.txt

The file holds the TURBO_TOKEN for this instance, the cache API URL (TURBO_API), and the team id (TURBO_TEAM, SecureAnyCloud). These values are unique to this instance. They are generated on first boot and never baked into the image.

The cache is never an open target. The command below reads the token straight from the root-only file, so it prints no secret. An authenticated request to the cache API returns HTTP 200. An anonymous request is rejected with HTTP 400 (missing header). A request with a wrong token is rejected with HTTP 401:

sudo systemctl start turborepo-remote-cache.service nginx.service 2>/dev/null || true sleep 2
T=$(sudo grep '^TURBO_TOKEN=' /root/turborepo-remote-cache-info.txt | cut -d= -f2-)
PH=$(head -c 64 /dev/urandom | sha256sum | awk '{print $1}')
curl -s -o /dev/null -w 'authenticated status: HTTP %{http_code}\n' -H "Authorization: Bearer $T" http://127.0.0.1/v8/artifacts/status
curl -s -o /dev/null -w 'anonymous artifact GET: HTTP %{http_code}\n' "http://127.0.0.1/v8/artifacts/$PH?teamId=sac"
curl -s -o /dev/null -w 'wrong-token artifact GET: HTTP %{http_code}\n' -H "Authorization: Bearer wrongtoken" "http://127.0.0.1/v8/artifacts/$PH?teamId=sac"

The authenticated request prints 200, the anonymous request prints 400, and the wrong-token request prints 401.

The Turborepo Remote Cache API is a content-addressed artifact store. A task output is stored with a PUT under its hash and retrieved with a GET. The block below performs a full authenticated round trip. It stores an artifact, retrieves it byte for byte, and confirms that an anonymous request for the same artifact is rejected. The token is read from the root-only file, so no secret is printed:

sudo systemctl start turborepo-remote-cache.service nginx.service 2>/dev/null || true sleep 2
T=$(sudo grep '^TURBO_TOKEN=' /root/turborepo-remote-cache-info.txt | cut -d= -f2-)
BLOB=$(head -c 512 /dev/urandom | base64 -w0)
H=$(printf '%s' "$BLOB" | sha256sum | awk '{print $1}')
PUT=$(printf '%s' "$BLOB" | curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $T" -H 'Content-Type: application/octet-stream' -X PUT --data-binary @- "http://127.0.0.1/v8/artifacts/$H?teamId=sac")
echo "authenticated PUT artifact ${H:0:12} HTTP $PUT"
GOT=$(curl -s -H "Authorization: Bearer $T" "http://127.0.0.1/v8/artifacts/$H?teamId=sac") [ "$GOT" = "$BLOB" ] && echo "authenticated GET artifact ${H:0:12} byte-for-byte match OK" || echo "MISMATCH"
UNG=$(curl -s -o /dev/null -w '%{http_code}' "http://127.0.0.1/v8/artifacts/$H?teamId=sac")
echo "anonymous GET artifact ${H:0:12} HTTP $UNG (rejected)"

The PUT returns 200, and the authenticated GET returns the artifact byte for byte. The anonymous GET is rejected. This is a full content-addressed round trip through the token-gated cache API.

From a client or CI runner, point Turborepo at your cache by setting the API URL, team and token. Replace <public-ip> with your instance's public IP, and <token> with the TURBO_TOKEN value from Step 4:

export TURBO_API=http://<public-ip>
export TURBO_TOKEN=<token>
export TURBO_TEAM=sac turbo build --remote-cache-timeout 60

On the first build, Turborepo uploads task outputs to the cache. On later builds, locally or in CI, on any machine that shares this configuration, Turborepo downloads the cached result instead of recomputing it. Verify connectivity from a client with a single authenticated request:

curl -H "Authorization: Bearer <token>" http://<public-ip>/v8/artifacts/status

Cache storage. Cache artifacts are stored on the local filesystem at /var/lib/turborepo-remote-cache/cache. Confirm free space with df -h /.

Non-secret configuration lives at /etc/turborepo-remote-cache/turbo-cache.env (the systemd EnvironmentFile). It holds AUTH_MODE=static, STORAGE_PROVIDER=local, the STORAGE_PATH, the loopback HOST/PORT and the body-size limit. The per-instance secret TURBO_TOKEN lives separately in /etc/turborepo-remote-cache/token.env (0600 root:root), which systemd reads at start.

nginx front end. The configuration is at /etc/nginx/sites-available/turborepo-remote-cache. The public / and /health endpoints are unauthenticated liveness probes. /v8/... is proxied to the cache server, which enforces the bearer token.

Per-instance secrets. The token copy in /root/turborepo-remote-cache-info.txt is 0600 root:root. The token is generated on first boot and never baked into the image. A fail-secure gate stops the cache from starting until the token exists.

TLS. Front the cache with your own domain and a CA-signed TLS certificate, for example an nginx :443 server block or an AWS load balancer that terminates TLS. This way the bearer token is never sent in clear text over the network.

sudo systemctl --no-pager --lines=3 status turborepo-remote-cache.service nginx.service | cat

Restart the cache with sudo systemctl restart turborepo-remote-cache. Reload nginx after a configuration change with sudo systemctl reload nginx. Both services are enabled at boot.