Self-hosted: el protocolo abierto y cuándo alojar tu caché

La caché remota alojada de Vercel es cómoda, pero no es magia propietaria: por debajo es un protocolo HTTP documentado —subir y bajar artefactos indexados por hash, acotados a un equipo—. Y un protocolo abierto se puede reimplementar. Existen servidores open source que hablan ese mismo protocolo y guardan los artefactos en tu propio S3, tu GCS o tu disco, y Turborepo apunta a cualquiera de ellos cambiando TURBO_API. El cliente no se entera: para turbo, tu caché self-hosted es indistinguible de la de Vercel. Alojarla tú es una decisión de soberanía y economía, no de capacidad.

El protocolo es abierto

El punto de partida es liberador: no hay nada secreto en cómo funciona la caché remota. El cliente sube un artefacto con un PUT a /v8/artifacts/:hash, lo descarga con un GET, consulta el estado con otras rutas, y autentica con el token y el equipo. Eso es todo. Cualquier servidor que responda a esas rutas es una caché remota válida para Turborepo, porque el cliente solo sabe hablar el protocolo; le da igual qué haya al otro lado.

Esa indiferencia del cliente es la propiedad de diseño más importante de todo el sistema. Significa que el acoplamiento entre tu build y tu caché es mínimo: una URL. No hay SDK propietario, ni formato secreto, ni dependencia de un proveedor; hay un contrato HTTP que cualquiera puede implementar y contra el que cualquiera puede migrar. En un mundo donde el vendor lock-in es la norma de las herramientas de infraestructura, que la caché se reduzca a un endpoint intercambiable es una libertad que conviene valorar.

Apuntar a un servidor propio es cambiar una variable. TURBO_API deja de valer el endpoint por defecto de Vercel y pasa a valer la URL de tu servidor; TURBO_TOKEN y TURBO_TEAM siguen cumpliendo su papel de autenticación y ámbito, ahora contra tu implementación.

export TURBO_API="https://cache.miempresa.dev"
export TURBO_TOKEN="un-token-que-valida-tu-servidor"
export TURBO_TEAM="plataforma"
turbo run build

Del lado del servidor hay varias implementaciones open source del protocolo. La más conocida es un servidor en Node —sobre Fastify— que actúa de adaptador: recibe los artefactos por el protocolo de Turborepo y los persiste en el almacenamiento que le configures, sea S3, Google Cloud Storage, Azure Blob o el disco local. Hay también reimplementaciones en otros lenguajes y despliegues serverless sobre tu propia nube. En el mundo de Nx el modelo es análogo aunque con otras piezas: Nx Cloud es la opción alojada, y para self-hosted existe la caché remota personalizada sobre tu propio bucket. En todos los casos la idea es la misma: el protocolo es el contrato, y el almacenamiento es un detalle que eliges.

# Configuracion tipica de un servidor de cache open source
storage:
  provider: s3
  bucket: turbo-cache-plataforma
  region: eu-west-1
tokens:
  - equipo: plataforma
    valor: un-token-que-valida-tu-servidor

El almacenamiento es intercambiable porque el servidor lo abstrae detrás del mismo protocolo. Puedes empezar con disco local para probar, migrar a un bucket de objetos cuando quieras compartir de verdad entre máquinas, y cambiar de proveedor más tarde sin que ninguna máquina cliente se entere, porque para turbo nada de eso existe: solo ve el endpoint. Esa indiferencia al backend es la contrapartida natural de que la caché sea un protocolo y no un producto; la sustancia está en el contrato HTTP, y todo lo demás es una decisión de operación que puedes cambiar sin tocar una línea del lado cliente.

flowchart LR
dev[Maquinas del equipo] -->|protocolo HTTP| srv[Servidor de cache open source]
ci[Jobs de CI] -->|TURBO_API apunta aqui| srv
srv --> store[Tu almacenamiento S3 o GCS]
style srv fill:#89b4fa,color:#11111b
style store fill:#f9e2af,color:#11111b

Poner en marcha uno de estos servidores es sorprendentemente poco ceremonioso. La implementación en Node, por ejemplo, se levanta como cualquier otro servicio, con unas pocas variables de entorno que le dicen qué backend de almacenamiento usar y qué tokens aceptar.

# Un servidor de cache open source apuntando a un bucket S3
docker run -p 3000:3000 \
  -e STORAGE_PROVIDER=s3 \
  -e STORAGE_PATH=turbo-cache-plataforma \
  -e TURBO_TOKEN=un-token-que-valida-tu-servidor \
  ghcr.io/ejemplo/turbo-remote-cache

A partir de ahí, apuntar TURBO_API a ese host es todo lo que separa a tu equipo de una caché compartida bajo tu control. La barrera de entrada, técnicamente, es baja: la sustancia difícil no está en encender el servidor, sino en mantenerlo sano, y de eso trata el resto de la lección.

Conviene situar esto en perspectiva histórica: la caché remota de artefactos no la inventó Turborepo. Sistemas de build como Bazel o Gradle llevan años ofreciendo cachés remotas e incluso ejecución remota, con la misma premisa —si el trabajo ya se hizo con estas entradas, no lo repitas— sobre protocolos propios. Lo que Turborepo y Nx aportan es llevar esa idea, antes reservada a la infraestructura de las grandes tecnológicas, al monorepo de JavaScript con dos comandos. Que ahora sea trivial no debe hacer olvidar que es una técnica madura y probada, no una moda pasajera.

Cuándo alojarla tú mismo, y cuándo no

Que puedas alojarla no significa que debas. La decisión se toma sopesando razones concretas a favor y un coste fijo en contra. A favor pesan cuatro motivos, y suele bastar uno serio. La residencia de datos: si tus artefactos y logs de build no pueden salir de tu nube o de una región concreta por cumplimiento normativo, la caché tiene que vivir donde tú controlas. El coste a gran escala: con tráfico de caché muy alto, guardar en tu propio S3 puede salir más barato que un servicio por asiento. El aislamiento: entornos on-premise o sin salida a internet no pueden depender de un SaaS externo. Y la proximidad: una caché en la misma red que tus runners reduce latencia y egreso frente a una remota.

En contra pesa una sola cosa, pero grande: alojar la caché significa que pasas a operar una pieza de infraestructura de build. Ya no es problema de otro que esté disponible, que no se llene, que sea segura, que se purgue. Para equipos pequeños, ese coste operativo casi nunca compensa frente a una caché alojada que es gratis en personal y barata en equipo y que no operas. La regla práctica: aloja cuando una razón de soberanía, coste o aislamiento lo exija, no porque suene a control; el control que ganas viene con una guardia que ahora es tuya.

El coste operativo es fácil de subestimar porque no se paga por adelantado, sino en forma de guardias futuras. El día que la caché se llene, que un token caduque o que la latencia se dispare, alguien de tu equipo tendrá que diagnosticarlo, y ese alguien probablemente preferiría estar construyendo producto. Alojar la caché es contratar, implícitamente, una pequeña responsabilidad de operaciones perpetua. Vale la pena cuando la soberanía o el coste lo justifican; no vale la pena por el placer abstracto de controlarlo todo.

Operar una caché compartida: evicción, autenticación y envenenamiento

Si decides alojarla, heredas una lista de responsabilidades que el SaaS te ocultaba. La primera es la evicción: los artefactos se acumulan sin fin, y cada cambio de código genera hashes nuevos; sin una política de purga —por tiempo de vida o por menos usado recientemente— tu almacenamiento crece sin techo. La segunda es la autenticación: emitir, validar y rotar los tokens que dan acceso, con el alcance mínimo para cada consumidor. La tercera es la observabilidad: sin métricas no sabes si la caché sirve, y la métrica que manda es la tasa de aciertos; una caché con hit rate bajo consume recursos sin devolver tiempo.

De esas responsabilidades, la evicción es la que más ingenieros subestiman. Un monorepo activo genera hashes nuevos con cada commit, y cada hash nuevo es un artefacto nuevo; sin purga, el almacenamiento crece de forma monótona hasta que el coste de guardar supera al de compilar, que es el colmo de la ironía. Las políticas habituales son por tiempo de vida —expulsar lo que no se ha tocado en semanas— o por capacidad, echando lo menos usado recientemente al llegar a un límite. Lo esencial es que la evicción sea segura por construcción: expulsar un artefacto solo puede provocar un miss, nunca un error, porque un miss se resuelve recompilando. La caché puede olvidar sin peligro; lo que no puede es mentir.

La autenticación, la segunda responsabilidad, tiene un matiz propio de un almacén compartido: no basta con un único token para todos. Lo maduro es emitir credenciales distintas para consumidores distintos —una para el CI de la rama principal con escritura, otra de solo lectura para los PRs, quizá una personal por desarrollador— de modo que revocar una no derribe a las demás y que un token filtrado tenga el menor alcance posible. Un solo token compartido por todo el mundo es cómodo el primer día y una pesadilla el día que hay que rotarlo.

Y la cuarta, la más delicada, es la seguridad frente al envenenamiento. Una caché compartida y escribible es una superficie de ataque: quien pueda escribir un artefacto bajo el hash de una tarea legítima puede repartir su salida manipulada a todo el que obtenga ese acierto. Las defensas son las mismas que en la caché alojada, ahora bajo tu responsabilidad de configurarlas: firma de artefactos con clave compartida para verificar integridad y procedencia, solo lectura para los escritores no confiables como los PRs de forks, y aislamiento correcto de las entradas para que un hash no colisione entre contextos que no deberían compartir salida. El envenenamiento de caché de build documentado en 2025 dejó la lección clara: en un almacén compartido, el peor fallo no es la caída, es la incorrección silenciosa, un artefacto malo que todos restauran creyendo que es bueno.

La observabilidad merece un apunte concreto porque es la que convierte todo lo anterior en algo gobernable. Sin un panel que muestre la tasa de aciertos, el tamaño medio de los artefactos y la latencia de las peticiones, operas a ciegas: no sabrías distinguir una caché sana de una que la gente ha dejado de usar en silencio porque se volvió más lenta que compilar. Esos tres números —cuánto aciertas, cuánto pesa cada acierto y cuánto tarda— son el cuadro de mandos mínimo de una caché self-hosted, y medirlos desde el primer día es mucho más barato que descubrir su ausencia el día que algo va mal.

Anatomía de una petición a la caché

Para desmitificar del todo el protocolo, vale la pena seguir una petición concreta. Cuando Turborepo quiere saber si existe el artefacto de un hash, hace un GET a /v8/artifacts/:hash con el token en la cabecera de autorización y el equipo como parámetro. Si el servidor responde con el cuerpo del artefacto, es un acierto; si responde que no existe, es un miss. Tras ejecutar en un miss, sube el resultado con un PUT a la misma ruta, con el tarball como cuerpo.

# Consulta (hit o miss) y subida, conceptualmente
GET  /v8/artifacts/3f8a1c2b?teamId=plataforma   -> 200 hay artefacto, o 404 no
PUT  /v8/artifacts/3f8a1c2b?teamId=plataforma   -> sube el tarball

Eso es, literalmente, casi todo el protocolo: consultar por hash, descargar, subir, y un endpoint auxiliar para registrar eventos de uso que alimentan las métricas. Su simplicidad es la razón de que existan tantas implementaciones: no hay nada complejo que replicar, solo un almacén indexado por clave detrás de tres o cuatro rutas HTTP. Cualquier cosa capaz de guardar y devolver bytes por una clave puede ser el fondo de esta API.

Entender el protocolo a este nivel tiene un valor práctico más allá de la curiosidad: te permite depurar con las herramientas de red de siempre. Un acierto que no llega, una subida que falla, una latencia sospechosa, todo se diagnostica mirando los códigos de estado de estas peticiones, igual que depurarías cualquier otra API HTTP.