### Copy Environment Example

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Copy the example environment variables file to create your own configuration.

```bash
cp .env.example .env
```

--------------------------------

### Install Dependencies

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Install all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Run Project in Development Mode

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Start the project in development mode using pnpm.

```bash
pnpm dev
```

--------------------------------

### Bundling Lambda Handler with esbuild

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/running-in-lambda.md

Example command to bundle the Lambda handler code and its dependencies using `esbuild`. This is a common method for preparing the code for deployment.

```bash
esbuild src/index.js --bundle --platform=node --outfile=dist/index.js
```

--------------------------------

### Run Remoteless with npx

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/deployment-environments.md

Execute the turborepo-remote-cache server directly using npx, provided Node.js is installed. Ensure environment variables are configured as required.

```bash
npx turborepo-remote-cache
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Examples of commit messages following Conventional Commits for Semantic Release. Use 'feat' for new features and 'fix' for bug fixes.

```git
feat: new feature ---> 1.x.0
fix: fix a bug ---> 1.0.x
```

--------------------------------

### Turborepo Client Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Configure a Turborepo monorepo to use the self-hosted cache server via `.turbo/config.json` or environment variables. Examples show local setup and Dockerfile usage.

```json
// .turbo/config.json
{
  "apiurl": "http://localhost:3000"
}
```

```bash
# Environment variables on developer machines / CI
export TURBO_API=http://localhost:3000
export TURBO_TEAM=my-org
export TURBO_TOKEN=my-secret-token

# Run a cached build
pnpm turbo build

# Alternatively, pass inline
turbo build --api="http://localhost:3000" --team="my-org" --token="my-secret-token"
```

```dockerfile
# Dockerfile — pass team and token securely as build args/secrets
ARG TURBO_TEAM
ENV TURBO_TEAM=$TURBO_TEAM

COPY turbo.json ./
COPY .turbo/config.json ./.turbo/

RUN --mount=type=secret,id=TURBO_TOKEN \
    TURBO_TOKEN=$(cat /run/secrets/TURBO_TOKEN) pnpm turbo build
```

--------------------------------

### AWS Lambda Handler Setup

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Export the AWS Lambda handler and configure environment variables for serverless deployments backed by S3. An IAM policy for S3 access is also required.

```javascript
// src/index.js — your Lambda package entry point
export { handler } from 'turborepo-remote-cache/aws-lambda'

// Build and bundle for Lambda deployment
// esbuild src/index.js --bundle --platform=node --outfile=dist/index.js

// Required Lambda environment variables:
// STORAGE_PROVIDER=s3
// STORAGE_PATH=my-turbo-cache-bucket
// TURBO_TOKEN=my-secret-token
// AWS_REGION=us-east-1  (or set via IAM role)

// Lambda IAM policy (inline JSON) for S3 access:
// {
//   "Version": "2012-10-17",
//   "Statement": [{
//     "Effect": "Allow",
//     "Action": ["s3:*"],
//     "Resource": [
//       "arn:aws:s3:::my-turbo-cache-bucket",
//       "arn:aws:s3:::my-turbo-cache-bucket/*"
//     ]
//   }]
// }
```

--------------------------------

### AWS S3 / DigitalOcean Spaces / MinIO Storage Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Configures artifact storage in an S3-compatible object store. This setup utilizes AWS SDK v3 and relies on the standard credential provider chain for authentication. Key environment variables include `STORAGE_PROVIDER`, `STORAGE_PATH` (bucket name), and AWS credentials/region. `S3_MAX_SOCKETS` can be adjusted for performance.

```dotenv
# .env — AWS S3
STORAGE_PROVIDER=s3
STORAGE_PATH=my-turbo-cache-bucket
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1
S3_MAX_SOCKETS=50
```

--------------------------------

### GET /v8/artifacts/status

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Check cache server status. Returns the enabled status and version of the cache server. Requires read authorization.

```APIDOC
## GET /v8/artifacts/status

### Description
Check cache server status. Returns the enabled status and version of the cache server. Requires read authorization. Log verbosity is controlled by the `ENABLE_STATUS_LOG` environment variable.

### Method
GET

### Endpoint
/v8/artifacts/status

### Request Example
```bash
# Static token auth
curl -s \
  -H "Authorization: Bearer my-secret-token" \
  http://localhost:3000/v8/artifacts/status

# With JWT auth
curl -s \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/v8/artifacts/status
```

### Response
#### Success Response (200)
- **status** (string) - Indicates if the cache server is enabled.
- **version** (string) - The version of the cache server.

#### Response Example
```json
{"status":"enabled","version":"2.8.6"}
```
```

--------------------------------

### GET /v8/artifacts/:id

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Retrieve a cached artifact. Downloads a cached build artifact as an `application/octet-stream` binary stream. Requires a `teamId`, `team`, or `slug` query parameter.

```APIDOC
## GET /v8/artifacts/:id

### Description
Retrieve a cached artifact. Downloads a cached build artifact as an `application/octet-stream` binary stream. Requires a `teamId`, `team`, or `slug` query parameter. If artifact signature verification is enabled (`TURBO_REMOTE_CACHE_SIGNATURE_KEY`), the `x-artifact-tag` header is included in the response.

### Method
GET

### Endpoint
/v8/artifacts/:id

### Parameters
#### Query Parameters
- **teamId** (string) - Required - The ID of the team.
- **team** (string) - Required - The team name.
- **slug** (string) - Required - The slug of the team (used by Turborepo when --team CLI flag is used).

### Request Example
```bash
# Fetch artifact for team "my-org"
curl -v \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org" \
  --output artifact.tar.gz

# With slug (used by Turborepo when --team CLI flag is used)
curl -v \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?slug=my-org" \
  --output artifact.tar.gz
```

### Response
#### Success Response (200)
- **Content-Type**: application/octet-stream
- **x-artifact-tag** (string) - Optional - HMAC signature if artifact signature verification is enabled.

#### Response Example
```bash
# 404 when artifact does not exist
# {"statusCode":404,"error":"Not Found","message":"Artifact not found"}
```
```

--------------------------------

### Retrieve Cached Artifact

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Use `GET /v8/artifacts/:id` to download a cached build artifact. Requires `teamId`, `team`, or `slug` query parameter. The `x-artifact-tag` header is included if signature verification is enabled.

```bash
# Fetch artifact for team "my-org"
curl -v \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org" \
  --output artifact.tar.gz

# With slug (used by Turborepo when --team CLI flag is used)
curl -v \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?slug=my-org" \
  --output artifact.tar.gz

# Response headers when signature verification is enabled:
# x-artifact-tag: sha256:e3b0c44298fc1c149afb...
# Content-Type: application/octet-stream

# 404 when artifact does not exist
# {"statusCode":404,"error":"Not Found","message":"Artifact not found"}
```

--------------------------------

### Create Fastify App Instance

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Use `createApp` to configure and initialize the Fastify server. Options include `trustProxy`, `bodyLimit`, and `configOverrides` for port, host, token, storage provider, and SSL/HTTP2 settings.

```typescript
import { createApp } from 'turborepo-remote-cache'

// Minimal local-storage server with a static token
const app = createApp({
  trustProxy: true,
  bodyLimit: 104_857_600, // 100 MB
  configOverrides: {
    PORT: 3000,
    HOST: '0.0.0.0',
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    STORAGE_PATH: 'turborepocache',
    STORAGE_PATH_USE_TMP_FOLDER: true,
  },
})

app.listen({ host: '0.0.0.0', port: 3000 }, (err) => {
  if (err) {
    app.log.error(err)
    process.exit(1)
  }
  // Server listening on http://0.0.0.0:3000
})
```

```typescript
// With HTTPS enabled
const httpsApp = createApp({
  trustProxy: true,
  configOverrides: {
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    SSL_KEY_PATH: '/etc/ssl/private/server.key',
    SSL_CERT_PATH: '/etc/ssl/certs/server.crt',
  },
})
```

```typescript
// With HTTP/2 (recommended for GCP Cloud Run to bypass 32 MiB limit)
const http2App = createApp({
  trustProxy: true,
  configOverrides: {
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    HTTP2: true,
  },
})
```

--------------------------------

### Navigate to Repository

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Change the current directory to the cloned repository folder.

```bash
cd turborepo-remote-cache
```

--------------------------------

### createApp

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Creates and configures the Fastify server with storage, authentication, and all remote-cache routes registered. Supports optional SSL and HTTP/2.

```APIDOC
## createApp(options?)

Creates and configures the Fastify server with storage, authentication, and all remote-cache routes registered. Supports optional SSL and HTTP/2. Used directly by the CLI entry point and the AWS Lambda handler.

```typescript
import { createApp } from 'turborepo-remote-cache'

// Minimal local-storage server with a static token
const app = createApp({
  trustProxy: true,
  bodyLimit: 104_857_600, // 100 MB
  configOverrides: {
    PORT: 3000,
    HOST: '0.0.0.0',
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    STORAGE_PATH: 'turborepocache',
    STORAGE_PATH_USE_TMP_FOLDER: true,
  },
})

app.listen({ host: '0.0.0.0', port: 3000 }, (err) => {
  if (err) {
    app.log.error(err)
    process.exit(1)
  }
  // Server listening on http://0.0.0.0:3000
})

// With HTTPS enabled
const httpsApp = createApp({
  trustProxy: true,
  configOverrides: {
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    SSL_KEY_PATH: '/etc/ssl/private/server.key',
    SSL_CERT_PATH: '/etc/ssl/certs/server.crt',
  },
})

// With HTTP/2 (recommended for GCP Cloud Run to bypass 32 MiB limit)
const http2App = createApp({
  trustProxy: true,
  configOverrides: {
    TURBO_TOKEN: 'my-secret-token',
    STORAGE_PROVIDER: 'local',
    HTTP2: true,
  },
})
```
```

--------------------------------

### Configure Build Script in package.json

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Add --team and --token parameters to Turborepo commands in package.json. This is less secure as the token is committed.

```json
//...
  "build": "turbo run build --team=\"ducktors\" --token=\"myGeneratedToken\"",
  "dev": "turbo run dev --parallel",
  "lint": "turbo run lint",
  "format": "prettier --write \"**/*.{ts,tsx,md}\""
//...
```

--------------------------------

### Configure DigitalOcean Spaces or MinIO

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Set environment variables for DigitalOcean Spaces or MinIO. Ensure the correct STORAGE_PROVIDER, STORAGE_PATH, and AWS credentials/endpoint are configured.

```bash
# .env — DigitalOcean Spaces
STORAGE_PROVIDER=s3
STORAGE_PATH=my-turbo-space
AWS_ACCESS_KEY_ID=<spaces-access-key>
AWS_SECRET_ACCESS_KEY=<spaces-secret-key>
AWS_REGION=us-east-1
S3_ENDPOINT=https://nyc3.digitaloceanspaces.com

# .env — MinIO (local or self-hosted)
STORAGE_PROVIDER=minio
STORAGE_PATH=turbo-cache
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://127.0.0.1:9000

# Run with Docker
docker run --env-file=.env -p 3000:3000 ducktors/turborepo-remote-cache
```

--------------------------------

### Configure Google Cloud Storage (Application Default Credentials)

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/supported-storage-providers.md

Configure Google Cloud Storage using Application Default Credentials (ADC). Leave GCS_* environment variables blank to enable ADC.

```sh
# .env
GCS_PROJECT_ID=
GCS_CLIENT_EMAIL=
GCS_PRIVATE_KEY=
```

--------------------------------

### Running Turborepo Remote Cache Server

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Instructions for running the turborepo-remote-cache server using different methods. Choose the method that best suits your deployment environment.

```bash
# Via npx (no install needed)
TURBO_TOKEN=secret STORAGE_PROVIDER=local npx turborepo-remote-cache
```

```bash
# Via Docker
docker run \
  -e TURBO_TOKEN=secret \
  -e STORAGE_PROVIDER=local \
  -p 3000:3000 \
  ducktors/turborepo-remote-cache
```

```bash
# Via Docker with .env file
docker run --env-file=.env -p 3000:3000 ducktors/turborepo-remote-cache
```

```bash
# Via npm / pnpm (installed globally or in project)
npm install -g turborepo-remote-cache
turborepo-remote-cache
```

```bash
# Development mode (from source)
git clone https://github.com/ducktors/turborepo-remote-cache.git
cd turborepo-remote-cache
pnpm install
cp .env.example .env   # edit .env with your configuration
pnpm dev
```

--------------------------------

### Configure Google Cloud Storage (Static Credentials)

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/supported-storage-providers.md

Configure Google Cloud Storage using static service account credentials by providing project ID, client email, and private key. Ensure these are kept secure.

```sh
# .env
GCS_PROJECT_ID=<project_id>
GCS_CLIENT_EMAIL=<client_email>
GCS_PRIVATE_KEY=<private_key>
```

--------------------------------

### Configure Google Cloud Storage (Bucket Name)

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/supported-storage-providers.md

Set the storage provider to Google Cloud Storage and specify the bucket name. This is a basic configuration step.

```sh
# .env
STORAGE_PROVIDER=google-cloud-storage
STORAGE_PATH=<name-of-the-bucket>
```

--------------------------------

### Vercel Serverless Deployment Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Use the provided `vercel.json` for one-click Vercel deployment. Configure required environment variables for the deployment.

```json
// vercel.json (included in the published package)
{
  "rewrites": [
    { "source": "/(.*)", "destination": "/api/vercel.js" }
  ]
}
```

```bash
# Required Vercel environment variables:
# NODE_ENV=production
# TURBO_TOKEN=my-secret-token
# STORAGE_PROVIDER=s3
# STORAGE_PATH=my-turbo-cache-bucket
# S3_ACCESS_KEY=AKIA...
# S3_SECRET_KEY=wJalr...
# S3_REGION=us-east-1

# Deploy via CLI
vercel deploy
```

--------------------------------

### Clone Repository

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/CONTRIBUTING.md

Clone the project repository to your local machine.

```bash
git clone git@github.com:ducktors/turborepo-remote-cache.git
```

--------------------------------

### Run Docker Image

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/deployment-environments.md

Execute the turborepo-remote-cache Docker image, mapping the host port to the container port and loading environment variables from a specified .env file.

```sh
docker run --env-file=.env -p 3000:3000 ducktors/turborepo-remote-cache
```

--------------------------------

### Configure Azure Blob Storage

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/supported-storage-providers.md

Set up Azure Blob Storage by providing the connection string. This is typically found in the Azure portal under the 'Access keys' blade.

```sh
ABS_CONNECTION_STRING=<connection_string>
```

--------------------------------

### Static Authentication Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Configures static authentication using pre-shared bearer tokens defined in the `TURBO_TOKEN` environment variable. Multiple tokens can be provided as a comma-separated list for different environments or agents. Requests without a valid token or missing the Authorization header will be rejected.

```dotenv
# .env — single token
TURBO_TOKEN=my-secret-token
AUTH_MODE=static
```

```dotenv
# .env — multiple tokens (e.g. for multiple CI agents)
TURBO_TOKEN=token-for-ci,token-for-dev,token-for-staging
```

```bash
# Start the server
PORT=3000 TURBO_TOKEN=my-secret-token npx turborepo-remote-cache
```

```bash
# Valid request
curl -H "Authorization: Bearer my-secret-token" \
  http://localhost:3000/v8/artifacts/status
```

```json
{"status":"enabled","version":"2.8.6"}
```

```bash
# Invalid token → 401
curl -H "Authorization: Bearer wrong-token" \
  http://localhost:3000/v8/artifacts/status
```

```json
{"statusCode":401,"error":"Unauthorized","message":"Invalid authorization token"}
```

```bash
# Missing header → 400
curl http://localhost:3000/v8/artifacts/status
```

```json
{"statusCode":400,"error":"Bad Request","message":"Missing Authorization header"}
```

--------------------------------

### Configure Google Cloud Storage

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Set environment variables for Google Cloud Storage. Supports explicit service account credentials or Application Default Credentials (ADC).

```bash
# .env — explicit service account credentials
STORAGE_PROVIDER=google-cloud-storage
STORAGE_PATH=my-turbo-cache-bucket
GCS_PROJECT_ID=my-gcp-project
GCS_CLIENT_EMAIL=turborepo@my-gcp-project.iam.gserviceaccount.com
GCS_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"

# .env — Application Default Credentials (ADC), e.g. on Cloud Run with Workload Identity
STORAGE_PROVIDER=google-cloud-storage
STORAGE_PATH=my-turbo-cache-bucket
# GCS_PROJECT_ID, GCS_CLIENT_EMAIL, GCS_PRIVATE_KEY intentionally omitted

# Run
docker run --env-file=.env -p 3000:3000 ducktors/turborepo-remote-cache
```

--------------------------------

### Configure Team and Token in .turbo/config.json

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Add teamslug and token properties to the config file for authentication. Note: storing the token here is less secure.

```json
{
  "apiurl": "http://cache.ducktors.dev",
  "teamslug": "ducktors",
  "token": "myGeneratedToken"
}
```

--------------------------------

### Build Docker Image with Remote Cache Server

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Command to build a Docker image, passing TURBO_TEAM as a build arg and TURBO_TOKEN as a secret.

```sh
# TURBO_TOKEN is an env variable preferably set from CI secrets
docker buildx build --progress=plain \
    --platform linux/amd64,linux/arm64 \
    -f Dockerfile . \
    --build-arg TURBO_TEAM="ducktors" \
    --secret id=TURBO_TOKEN,env=TURBO_TOKEN \
    --no-cache
```

--------------------------------

### Configure Azure Blob Storage

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Set environment variables for Azure Blob Storage using a connection string. A TURBO_TOKEN is also required.

```bash
# .env
STORAGE_PROVIDER=azure-blob-storage
STORAGE_PATH=turbo-cache-container
ABS_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=abc123==;EndpointSuffix=core.windows.net"
TURBO_TOKEN=my-secret-token

# Run
docker run --env-file=.env -p 3000:3000 ducktors/turborepo-remote-cache
```

--------------------------------

### Upload Artifact with Signature

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Uploads a build artifact with a signature key. Ensure TURBO_REMOTE_CACHE_SIGNATURE_KEY is set for this to be effective. Handles potential storage failures by returning a 412 status code, which triggers a Turborepo retry.

```bash
curl -v \
  -X PUT \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/octet-stream" \
  -H "x-artifact-tag: sha256:e3b0c44298fc1c149afb4c8996fb92427ae41e4649b934ca495991b7852b855" \
  --data-binary @./build-output.tar.gz \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"
```

```json
{"statusCode":412,"error":"Precondition Failed","message":"Error during the artifact creation"}
```

--------------------------------

### Local Filesystem Storage Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Configures artifact storage on the local filesystem. By default, it uses the system's temporary directory. For persistent storage, especially in containerized environments like Cloud Run, a mounted volume is recommended. Ensure `STORAGE_PATH_USE_TMP_FOLDER` is set to `false` when using an absolute path.

```dotenv
# .env — store under /tmp/turborepocache (default)
STORAGE_PROVIDER=local
STORAGE_PATH=turborepocache
STORAGE_PATH_USE_TMP_FOLDER=true
```

```dotenv
# .env — store at an absolute path (e.g., a mounted volume)
STORAGE_PROVIDER=local
STORAGE_PATH=/mnt/cache/turbo
STORAGE_PATH_USE_TMP_FOLDER=false
```

```bash
# Run via npx
TURBO_TOKEN=secret STORAGE_PROVIDER=local npx turborepo-remote-cache
```

--------------------------------

### Turborepo Remote Cache Environment Variables Reference

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

This is a comprehensive list of all supported configuration environment variables for the turborepo-remote-cache server. It includes settings for server, authentication, storage, and logging.

```bash
# .env.example — full configuration reference

# Server
NODE_ENV=production           # development | production | test
PORT=3000                     # HTTP port (default: 3000)
HOST=0.0.0.0                  # Bind address (0.0.0.0 = all IPv4, :: = all)
BODY_LIMIT=104857600          # Max upload size in bytes (default: 100 MB)
HTTP2=false                   # Enable HTTP/2 (required for Cloud Run >32 MiB)
SSL_KEY_PATH=                 # Path to TLS private key (enables HTTPS)
SSL_CERT_PATH=                # Path to TLS certificate (enables HTTPS)

# Authentication
AUTH_MODE=static              # static | jwt | none
TURBO_TOKEN=secret1,secret2  # Comma-separated tokens (required for static)
JWKS_URL=                     # JWKS endpoint URL (required for jwt)
JWT_ISSUER=                   # Expected JWT issuer (optional)
JWT_AUDIENCE=                 # Expected JWT audience (optional)
JWT_READ_SCOPES=cache:read    # Required scope for read operations (optional)
JWT_WRITE_SCOPES=cache:write  # Required scope for write operations (optional)

# Storage
STORAGE_PROVIDER=local        # local | s3 | minio | google-cloud-storage | azure-blob-storage
STORAGE_PATH=turborepocache   # Folder name (local) or bucket name (cloud)
STORAGE_PATH_USE_TMP_FOLDER=true  # Prefix STORAGE_PATH with OS temp dir

# AWS S3 / MinIO / DigitalOcean Spaces
S3_ACCESS_KEY=                # AWS access key ID
S3_SECRET_KEY=                # AWS secret access key
S3_REGION=us-east-1           # AWS region
S3_ENDPOINT=                  # Custom endpoint for S3-compatible stores
S3_MAX_SOCKETS=50             # Max concurrent S3 connections

# Google Cloud Storage
GCS_PROJECT_ID=
GCS_CLIENT_EMAIL=
GCS_PRIVATE_KEY=

# Azure Blob Storage
ABS_CONNECTION_STRING=

# Artifact signing
TURBO_REMOTE_CACHE_SIGNATURE_KEY=  # Shared secret for HMAC artifact signing

# Logging
LOG_LEVEL=info                # trace | debug | info | warn | error | fatal
LOG_MODE=stdout               # stdout | file
LOG_FILE=server.log           # Path when LOG_MODE=file
ENABLE_STATUS_LOG=true        # Log requests to /v8/artifacts/status

```

--------------------------------

### Check Cache Server Status

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Use the `/v8/artifacts/status` endpoint to check if the cache server is enabled and its version. Requires read authorization. Log verbosity is controlled by `ENABLE_STATUS_LOG`.

```bash
# Static token auth
curl -s \
  -H "Authorization: Bearer my-secret-token" \
  http://localhost:3000/v8/artifacts/status

# Expected response
# {"status":"enabled","version":"2.8.6"}
```

```bash
# With JWT auth
curl -s \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/v8/artifacts/status
```

--------------------------------

### Enable Remote Caching in Dockerfile

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Configure Dockerfile to accept TURBO_TEAM as a build arg and TURBO_TOKEN as a build secret for remote caching.

```dockerfile
ARG TURBO_TEAM
ENV TURBO_TEAM=$TURBO_TEAM

ARG TURBO_TOKEN
ENV TURBO_TOKEN=$TURBO_TOKEN

COPY turbo.json ./
COPY .turbo/config.json ./.turbo/

RUN --mount=type=bind,source=.git,target=.git \
    --mount=type=secret,id=TURBO_TOKEN \
    TURBO_TOKEN=$(cat /run/secrets/TURBO_TOKEN) pnpm turbo build
```

--------------------------------

### PUT /v8/artifacts/:id

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Upload a cached artifact. Stores a build artifact binary for a given team. Body must be `application/octet-stream`.

```APIDOC
## PUT /v8/artifacts/:id

### Description
Upload a cached artifact. Stores a build artifact binary for a given team. Body must be `application/octet-stream`. If `TURBO_REMOTE_CACHE_SIGNATURE_KEY` is configured, the optional `x-artifact-tag` header (HMAC signature) is stored alongside the artifact.

### Method
PUT

### Endpoint
/v8/artifacts/:id

### Parameters
#### Query Parameters
- **teamId** (string) - Required - The ID of the team.

#### Request Body
- **artifact** (binary) - Required - The artifact binary stream (`application/octet-stream`).

#### Headers
- **x-artifact-tag** (string) - Optional - HMAC signature if artifact signature verification is enabled.

### Request Example
```bash
# Upload a new artifact
curl -v \
  -X PUT \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./build-output.tar.gz \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"
```

### Response
#### Success Response (200)
- **urls** (array) - An array containing the URL(s) where the artifact is stored.

#### Response Example
```json
{"urls":["my-org/abc123def456"]}
```
```

--------------------------------

### Docker Environment Variables

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/deployment-environments.md

Define necessary environment variables for the Docker deployment in an .env file. Refer to the environment variables documentation for details.

```sh
NODE_ENV=
PORT=
TURBO_TOKEN=
LOG_LEVEL=
STORAGE_PROVIDER=
STORAGE_PATH=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
S3_ENDPOINT=
```

--------------------------------

### Configure API URL in .turbo/config.json

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Specify the address of your turborepo-remote-cache server in the config file.

```json
{
  "apiurl": "http://cache.ducktors.dev"
}
```

--------------------------------

### Enable Remote Cache Signature in turbo.json

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/custom-remote-caching.md

Add the `signature: true` property to the `remoteCache` section in your `turbo.json` to enable artifact signing.

```json
{
  "remoteCache": {
    "signature": true
  }
}
```

--------------------------------

### Upload Cached Artifact

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Use `PUT /v8/artifacts/:id` to store a build artifact. The body must be `application/octet-stream`. An optional `x-artifact-tag` header can be included if signature verification is configured.

```bash
# Upload a new artifact
curl -v \
  -X PUT \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./build-output.tar.gz \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"

# Expected response
# {"urls":["my-org/abc123def456"]}
```

--------------------------------

### JWT Authentication Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Enables JWT authentication, verifying tokens against a specified JWKS endpoint. Supports granular authorization using `JWT_READ_SCOPES` and `JWT_WRITE_SCOPES` for read and write operations respectively. Invalid JWTs or missing required scopes result in 401 or 403 errors.

```dotenv
# .env
AUTH_MODE=jwt
JWKS_URL=https://your-idp.example.com/.well-known/jwks.json
JWT_ISSUER=https://your-idp.example.com/
JWT_AUDIENCE=turborepo-cache
JWT_READ_SCOPES=cache:read
JWT_WRITE_SCOPES=cache:write
```

```bash
# Request with a JWT
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/v8/artifacts/status
```

```json
{"status":"enabled","version":"2.8.6"}
```

```json
# JWT missing required scope → 403
{"statusCode":403,"error":"Forbidden","message":"Forbidden"}
```

```json
# Invalid JWT → 401
{"statusCode":401,"error":"Unauthorized","message":"Unauthorized"}
```

--------------------------------

### Record Artifact Cache Events (POST)

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Accepts telemetry events from the Turborepo client, such as cache hits and misses. This endpoint is a no-op stub designed to maintain API compatibility and always returns a 200 OK with an empty JSON object.

```bash
curl -v \
  -X POST \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '[{"sessionId":"abc","source":"LOCAL","event":"HIT","hash":"abc123","duration":12}]' \
  "http://localhost:3000/v8/artifacts/events"
```

```json
{}
```

--------------------------------

### Turborepo Remote Cache Lambda Handler

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/running-in-lambda.md

The entry point for the AWS Lambda function. It exports the handler from the `turborepo-remote-cache` package. Dependencies must be bundled before deployment.

```javascript
export { handler } from 'turborepo-remote-cache/aws-lambda';
```

--------------------------------

### Check Artifact Existence (HEAD)

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Checks if a cached artifact exists without downloading its content. Returns 200 if found, 404 if not. Signature verification is also performed if enabled. The `team` query parameter can be used as an alternative to `teamId`.

```bash
# Check if artifact exists
curl -v \
  -X HEAD \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"
```

```bash
# Using team query param instead of teamId
curl -v \
  -X HEAD \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?team=my-org"
```

--------------------------------

### No Authentication Configuration

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Disables all built-in authentication mechanisms. This mode is intended for scenarios where authentication is handled externally, such as by an API gateway or ingress controller.

```dotenv
# .env
AUTH_MODE=none
```

```bash
# No Authorization header required
curl http://localhost:3000/v8/artifacts/status
```

```json
{"status":"enabled","version":"2.8.6"}
```

--------------------------------

### Upload Artifact with Signature

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Uploads an artifact to the remote cache. This endpoint requires authentication and supports signature verification if TURBO_REMOTE_CACHE_SIGNATURE_KEY is set. It returns a 412 status code on storage failure to trigger retries.

```APIDOC
## PUT /v8/artifacts/:id

### Description
Uploads an artifact to the remote cache. Requires authentication and supports signature verification.

### Method
PUT

### Endpoint
`/v8/artifacts/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the artifact.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/octet-stream` for artifact data.
- **x-artifact-tag** (string) - Optional - SHA256 hash for artifact signature verification.

### Request Example
```bash
curl -v \
  -X PUT \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/octet-stream" \
  -H "x-artifact-tag: sha256:e3b0c44298fc1c149afb4c8996fb92427ae41e4649b934ca495991b7852b855" \
  --data-binary @./build-output.tar.gz \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"
```

### Response
#### Error Response (412)
- **statusCode** (integer) - `412`
- **error** (string) - `Precondition Failed`
- **message** (string) - `Error during the artifact creation`
```

--------------------------------

### Check Artifact Existence

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Checks if a cached artifact exists without downloading its content. Returns a 200 OK if found, and 404 Not Found if the artifact is missing. If signature verification is enabled, it also verifies the artifact tag.

```APIDOC
## HEAD /v8/artifacts/:id — Check artifact existence

### Description
Checks whether a cached artifact exists without downloading it. Returns `200` if found, `404` if not. If signature verification is enabled, also verifies the artifact tag exists.

### Method
HEAD

### Endpoint
`/v8/artifacts/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the artifact.

#### Query Parameters
- **teamId** (string) - Required - The ID of the team associated with the artifact.
- **team** (string) - Required - The name of the team associated with the artifact (alternative to `teamId`).

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
# Check if artifact exists
curl -v \
  -X HEAD \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?teamId=my-org"

# Using team query param instead of teamId
curl -v \
  -X HEAD \
  -H "Authorization: Bearer my-secret-token" \
  "http://localhost:3000/v8/artifacts/abc123def456?team=my-org"
```

### Response
#### Success Response (200)
Indicates the artifact exists.

#### Not Found Response (404)
Indicates the artifact does not exist.

#### Example Responses
```
# HTTP/1.1 200 OK  — artifact exists
# HTTP/1.1 404 Not Found — artifact missing
```
```

--------------------------------

### Artifact Integrity and Authenticity Verification

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Enable signature verification in Turborepo by setting `TURBO_REMOTE_CACHE_SIGNATURE_KEY` on both the client and server. Configure `turbo.json` to enable this feature.

```json
// turbo.json — enable signature verification on the client
{
  "remoteCache": {
    "signature": true
  }
}
```

```bash
# Both the cache server and Turborepo client must share the same key

# Cache server .env
TURBO_REMOTE_CACHE_SIGNATURE_KEY=a-strong-random-secret-key

# Client CI environment
export TURBO_REMOTE_CACHE_SIGNATURE_KEY=a-strong-random-secret-key
export TURBO_API=https://cache.example.com
export TURBO_TEAM=my-org
export TURBO_TOKEN=my-secret-token
pnpm turbo build
```

--------------------------------

### Record Artifact Cache Events

Source: https://context7.com/ducktors/turborepo-remote-cache/llms.txt

Accepts telemetry events from Turborepo clients, such as cache hits and misses. This endpoint is a no-op stub designed to maintain API compatibility and always returns a 200 OK with an empty JSON object.

```APIDOC
## POST /v8/artifacts/events — Record artifact cache events

### Description
Accepts Turborepo client telemetry events (cache hits/misses). The endpoint always returns `200 {}`. It is a no-op stub to maintain full API compatibility with the official Turborepo Remote Cache protocol.

### Method
POST

### Endpoint
`/v8/artifacts/events`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - `application/json` for the event data.

#### Request Body
- **events** (array) - Required - An array of telemetry event objects.
  - **sessionId** (string) - Required - The session identifier.
  - **source** (string) - Required - The source of the event (e.g., `LOCAL`).
  - **event** (string) - Required - The type of event (e.g., `HIT`, `MISS`).
  - **hash** (string) - Required - The artifact hash.
  - **duration** (integer) - Required - The duration of the operation in milliseconds.

### Request Example
```bash
curl -v \
  -X POST \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '[{"sessionId":"abc","source":"LOCAL","event":"HIT","hash":"abc123","duration":12}]' \
  "http://localhost:3000/v8/artifacts/events"
```

### Response
#### Success Response (200)
- **{}** (object) - An empty JSON object, indicating success.

```
# HTTP/1.1 200 OK
# {}
```
```

--------------------------------

### Lambda IAM Policy for S3 Access

Source: https://github.com/ducktors/turborepo-remote-cache/blob/main/docs/running-in-lambda.md

This policy grants the Lambda function permissions to access a specific S3 bucket for storing and retrieving artifacts. Ensure `<your_bucket_name>` is replaced with your actual bucket name.

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:*"
            ],
            "Resource": [
                "arn:aws:s3:::<your_bucket_name>",
                "arn:aws:s3:::<your_bucket_name>/*"
            ]
        }
    ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.