# turborepo-remote-cache: self-hosted Turborepo cache review

> turborepo-remote-cache is an open source TypeScript implementation of a Turborepo custom remote cache server. It suits monorepo teams needing self-hosted deployment and storage choice, provided they are prepared to operate authentication, credentials, and cache infrastructure.

**ducktors/turborepo-remote-cache** — Open source implementation of the Turborepo custom remote cache server.

- Repository: https://github.com/ducktors/turborepo-remote-cache
- Website: https://ducktors.github.io/turborepo-remote-cache/
- Stars: 1,492 · Forks: 159
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ducktors-turborepo-remote-cache

## The cache-control problem addressed by turborepo-remote-cache

Turborepo uses cached task artifacts to avoid repeating suitable work across runs. `turborepo-remote-cache` implements the server side of Turborepo's custom remote cache protocol for teams that need a deployment outside Vercel's official cache service. The README calls it an open source alternative for self-hosted deployments, which makes the project relevant to organizations that want control over where build artifacts are stored and how the cache endpoint is operated.

The intended users are platform engineers, DevOps teams, and maintainers of Turborepo monorepos. They are likely to be managing CI systems, package graphs, build outputs, storage credentials, and network access between developers or runners and persistent storage. A developer who only wants Turborepo's built-in caching behavior does not necessarily need another service. The value here comes from deployment choice, not from replacing Turborepo itself.

Self-hosting creates a clear trade-off. The project may fit an infrastructure model better than a hosted option, but operators still need to configure a storage backend, protect the endpoint, determine authentication behavior, and monitor service availability. The server centralizes those controls in one application; it does not remove the infrastructure decisions from the adopting team.

## Package structure for server, CLI, and Lambda deployments

The primary implementation is TypeScript, and the repository topics identify Fastify and Node.js as part of the stack. The `package.json` exposes the main module as `./dist/app.js`, a CLI named `turborepo-remote-cache` at `./dist/cli.js`, and a separate `./dist/aws-lambda` entry point. This is a useful distinction for adoption because the project can be packaged for more than one execution model rather than existing only as an application tied to one host.

The build script compiles the TypeScript project into `dist`, while the development scripts run the source through `tsx` and perform a separate type check. The package also defines Docker-related build behavior. The Dockerfile uses Node.js 24 Alpine images, prepares pnpm 10.33.0, installs locked dependencies without lifecycle scripts in the build stage, compiles the application, and produces a production image containing `dist`, production dependencies, and `package.json`.

That Docker flow gives operators a concrete deployment artifact rather than requiring all runtime assembly to happen on the target host. It also makes operational decisions visible. The final image runs as a non-root application user, starts Node.js through `tini`, and sets `NODE_ENV=production`. Those are useful deployment properties, but they do not configure a storage provider or secure credentials automatically.

## Storage-provider routing and cache read behavior

The service selects its persistent storage layer through `STORAGE_PROVIDER`. The environment template includes AWS S3 credentials and endpoint settings, Google Cloud Storage fields, and Azure Blob Storage configuration. These variables show a storage abstraction spanning object storage services. The README also links to separate documentation for supported storage providers, so the exact accepted provider names and provider-specific requirements should be checked there before deployment.

The most interesting routing choice is `TURBO_CACHE_READ_URL`. Its comment in `.env.example` states that `GET` and `HEAD` cache reads can use a `302` redirect to a CDN or proxy rather than streaming the artifact from the configured provider. Writes still go to `STORAGE_PROVIDER`. In other words, this option separates the route used to retrieve an artifact from the destination that receives newly uploaded artifacts.

That design can be appropriate when reads need CDN delivery or a separate proxy tier. It also introduces another operational dependency. A successful write does not by itself prove that redirected reads will work, because the read URL, permissions, redirects, client behavior, and origin accessibility all affect retrieval. Local filesystem settings such as `STORAGE_PATH` and `STORAGE_PATH_USE_TMP_FOLDER` are also present.

## Authentication, signatures, and network exposure

A remote cache contains build outputs, so access control cannot be treated as an incidental deployment concern. The environment template supports a `TURBO_TOKEN` and also defines JWT-related settings: `JWKS_URL`, `JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_READ_SCOPES`, and `JWT_WRITE_SCOPES`. The presence of separate read and write scopes indicates that the application can distinguish cache retrieval from artifact upload when configured for JWT authentication.

Optional artifact verification is configured through `TURBO_REMOTE_CACHE_SIGNATURE_KEY`. The application also defines `BODY_LIMIT`, which can constrain accepted request bodies, and HTTPS-related settings including `HTTP2`, `SSL_KEY_PATH`, and `SSL_CERT_PATH`. These options matter because cache clients must both reach the server and exchange artifacts with it correctly.

The repository layout includes `SECURITY.md`, but its contents are not included here, so its reporting and support details cannot be confirmed. Likewise, the documentation excerpt does not explain token rotation, cache eviction, rollback, backup validation, or recovery after storage loss. Those omissions matter for a service that participates in CI. Authentication configuration is documented as available capability, while operational procedures beyond that configuration need independent verification.

## Installing from source and starting the development server

The README provides a source-development path rather than a complete end-user installation command for an existing package. Clone the repository, enter its directory, install the pnpm dependencies, copy the example environment file, and fill in the variables required by the selected storage and authentication setup.

The following commands are copied from the README:

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

After the checkout is available, create the local environment file:

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

Open `.env`, set the storage provider and its associated credentials, then start the development process:

```bash
pnpm dev
```

The `dev` script runs `dev:start` and `check:types` together. In development mode, `dev:start` invokes `tsx watch --inspect --env-file=.env src/index.ts`. The reader should therefore have Node.js and pnpm available before starting, with the environment file completed according to the linked environment-variable documentation. The Dockerfile declares `24-alpine` and the README badge shows `node:24`.

This is a development setup, not a complete production deployment guide. The README separately links to deployment instructions and one-click deployment options where available.

## Production maintenance, releases, and Docker operating cost

The repository is not archived. Its last push was on 2026-10-14, and recent releases include `v2.14.3` on 2026-10-07, `v2.14.2` on 2026-10-02, and `v2.14.1` on 2026-09-17. This supports the conclusion that the repository was receiving recent development at the time represented by the project data, but it does not establish compatibility with every future Turborepo version.

The project uses Semantic Release with Conventional Commits. The README states that a `feat` commit produces a minor release and a `fix` commit produces a patch release. That scheme gives adopters a documented relationship between commit intent and release type, although ordinary dependency upgrades or deployment changes may still require their own review.

The MIT license permits use and modification under the license's terms, but organizations still need to review the actual `LICENSE` file and comply with its notice requirements. Running the service also creates costs beyond the package itself: compute for the server, network transfer for cache reads and writes, storage consumption, credential management, and engineering time for upgrades. `TURBO_CACHE_READ_URL` may move some delivery through a CDN or proxy, but that adds another service whose behavior and cost must be evaluated.

## Limits of turborepo-remote-cache versus the official service

The clearest alternative is Vercel's official Turborepo cache service. The README explicitly presents `turborepo-remote-cache` as an option for situations in which the official Vercel server is not viable. The approaches therefore differ in control: the official service avoids operating a separate cache server, while this project places deployment, provider selection, networking, and authentication configuration under the adopter's control.

This project is the wrong choice when its operational ownership is not available. It also fits poorly if the goal is merely to speed up a local monorepo without a shared remote cache requirement. The README does not claim that deploying the server guarantees cache hits, so teams should not treat it as a performance improvement by itself. Cache effectiveness still depends on Turborepo configuration, compatible tasks, artifact availability, and successful remote read and write requests.

Before committing, compare the official service against the selected self-hosted storage path on authentication, data location, recovery, network access, and maintenance ownership. The deciding technical question is not whether this server can run, but whether the organization can operate a dependable cache boundary with the exact provider and security settings its Turborepo clients require.

## Conclusion

Adopt turborepo-remote-cache when the organization requires self-hosted Turborepo caching and has capacity to operate storage, credentials, authentication, and deployment infrastructure. Do not introduce it when Vercel's official cache server already satisfies the requirement or when no team can own those operational duties. Before adoption, verify the provider configuration, authentication choice, artifact signature settings, backup expectations, and upgrade procedure against the intended environment. The first concrete acceptance boundary is a successful remote-cache round trip through the selected storage provider.

## FAQ

### What is turborepo-remote-cache used for?

It is an open source implementation of the Turborepo custom remote cache server for self-hosted deployments. The README identifies it as an alternative when Vercel's official cache server is not viable.

### How do I run turborepo-remote-cache locally?

The README instructs contributors to clone the repository, run `pnpm install`, copy `.env.example` to `.env`, fill in the environment variables, and run `pnpm dev`. The development script starts the TypeScript server with `.env` loaded and also performs a type check.

### Does turborepo-remote-cache support self-hosted storage?

The environment template exposes AWS S3, Google Cloud Storage, and Azure Blob Storage settings, as well as `STORAGE_PROVIDER` and `STORAGE_PATH`. The README links to separate documentation for the full list of supported storage providers.

## Sources

- [ducktors/turborepo-remote-cache on GitHub](https://github.com/ducktors/turborepo-remote-cache)
- [License: MIT](https://github.com/ducktors/turborepo-remote-cache/blob/main/LICENSE)
- [Project website](https://ducktors.github.io/turborepo-remote-cache/)
- [README](https://github.com/ducktors/turborepo-remote-cache/blob/main/README.md)
- [Releases](https://github.com/ducktors/turborepo-remote-cache/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ducktors-turborepo-remote-cache