Artifacts, un sistema de almacenamiento con control de versiones compatible con Git

Los agentes han cambiado nuestra forma de pensar sobre el control de código fuente, los sistemas de archivos y la persistencia del estado. Los desarrolladores y los agentes están generando más código que nunca — se escribirá más código en los próximos 5 años que en toda la historia de la programación — y esto ha impulsado un cambio de orden de magnitud en la escala de los sistemas necesarios para satisfacer esta demanda. Las plataformas de control de código fuente tienen dificultades especialmente aquí. Se crearon para satisfacer las necesidades de los humanos, no un cambio de 10 veces en volumen impulsado por agentes que nunca duermen, pueden trabajar en varios problemas a la vez y nunca se cansan.

Creemos que se necesita una nueva primitiva. Un sistema de archivos distribuido y con control de versiones, diseñado ante todo para los agentes y capaz de dar servicio a los tipos de aplicaciones que se están desarrollando en la actualidad.

Lo hemos bautizado como Artifacts: un sistema de archivos con control de versiones que funciona con Git. Puedes crear repositorios mediante programación, junto con tus agentes, espacios seguros, Workers o cualquier otro paradigma informático, y conectarte a ellos desde cualquier cliente Git normal.

¿Quieres que cada sesión de agente tenga un repositorio? Artifacts puede hacerlo. ¿Cada instancia del entorno aislado? También Artifacts. ¿Quieres crear 10 000 bifurcaciones a partir de un punto de partida conocido? Lo has adivinado: Artifacts de nuevo. Artifacts ofrece una API REST y una API nativa de Workers para crear repositorios, generar credenciales y realizar confirmaciones en entornos en los que un cliente Git no es la opción más adecuada (por ejemplo, en cualquier función sin servidor).

Artifacts está disponible en versión beta privada para todos los desarrolladores que cuenten con el plan de pago de Workers, y nuestro objetivo es lanzarla como beta pública a principios de mayo.

// Create a repo
const repo = await env.AGENT_REPOS.create(name)
// Pass back the token & remote to your agent
return { repo.remote, repo.token }

# Clone it and use it like any regular git remote
$ git clone https://x:${TOKEN}@123def456abc.artifacts.cloudflare.net/git/repo-13194.git

Eso es todo. Un repositorio básico, listo para usar, creado sobre la marcha, con el que cualquier cliente git puede operar.

Y si quieres inicializar un repositorio de Artifacts desde un repositorio Git existente para que tu agente pueda trabajar en él de forma independiente e impulsar cambios independientes, también puedes hacerlo con .import():

interface Env {
  ARTIFACTS: Artifacts
}

export default {
  async fetch(request: Request, env: Env) {
    // Import from GitHub
    const { remote, token } = await env.ARTIFACTS.import({
      source: {
        url: "https://github.com/cloudflare/workers-sdk",
        branch: "main",
      },
      target: {
        name: "workers-sdk",
      },
    })

    // Get a handle to the imported repo
    const repo = await env.ARTIFACTS.get("workers-sdk")

    // Fork to an isolated, read-only copy
    const fork = await repo.fork("workers-sdk-review", {
      readOnly: true,
    })

    return Response.json({ remote: fork.remote, token: fork.token })
  },
}

Consulta la documentación para empezar, o si quieres entender cómo se utiliza Artifacts, cómo se desarrolló y cómo funciona internamente, sigue leyendo.

Los agentes conocen Git. Se encuentra en los datos de entrenamiento de la mayoría de los modelos. Los agentes conocen bien tanto el flujo normal como los casos extremos, y los modelos optimizados para código (y/o los entornos de prueba) son especialmente eficaces a la hora de utilizar Git.

Además, el modelo de datos de Git no solo resulta útil para el control de versiones, sino también para cualquier tarea en la que sea necesario realizar un seguimiento del estado, retroceder en el tiempo y almacenar grandes cantidades de datos de pequeño tamaño. Código, configuración, instrucciones de sesión e historial del agente: todos estos son elementos ("objetos") que a menudo se desea almacenar en pequeños fragmentos ("commits") y poder revertir o volver atrás ("historial"). 

Podríamos haber inventado un protocolo completamente nuevo y personalizado... pero luego tienes el problema de arranque. Los modelos de la IA no lo saben, así que tienes que distribuir herramientas, o una CLI, o esperar que los usuarios estén conectados a tu MCP de documentos... todo ello supone un obstáculo. ¿Y si pudiéramos proporcionar a los agentes una URL remota de Git HTTPS autenticada y segura y hacer que funcionaran como si se tratara de un repositorio de Git? Resulta que eso funciona bastante bien. Y para los clientes que no utilizan Git, como Cloudflare Worker, una función Lambda o una aplicación Node.js, hemos puesto a su disposición una API REST y (próximamente) SDK específicos para cada lenguaje. Esos clientes también pueden utilizar isomorphic-git, pero en muchos casos una API TypeScript más sencilla puede reducir la superficie de API necesaria.

La API de Git de Artifacts podría llevarte a pensar que solo sirve para el control de versiones, pero resulta que la API y el modelo de datos de Git constituyen una potente herramienta para conservar el estado de los datos, lo que te permite crear bifurcaciones, retroceder en el tiempo y comparar cambios en cualquier conjunto de datos.

En Cloudflare, utilizamos Artifacts para nuestros agentes internos. Conservamos automáticamente el estado actual del sistema de archivos y el historial de la sesión en un repositorio de Artifacts por sesión. Esto nos permite:

• Conservar el estado de entorno aislado sin tener que aprovisionar (y mantener) el almacenamiento en bloques.

• Compartir sesiones con otras personas y permitirles retroceder en el tiempo tanto por el estado de la sesión (instrucciones) como por el estado del archivo, independientemente de si se han realizado confirmaciones en el repositorio "real" (control de versiones).

• Y lo mejor: bifurcar una sesión desde cualquier punto, lo que permite a nuestro equipo compartir sesiones con un compañero de trabajo y que este la retome. ¿Estás depurando algo y quieres otro par de ojos? Envía una URL y haz una bifurcación. ¿Quieres probar una API? Pídele a un compañero de trabajo que lo bifurque y retome desde donde lo dejaste.

También hemos hablado con equipos que quieren utilizar Artifacts en casos en los que el protocolo Git no es un requisito, pero la semántica (reversión, clonación, diferenciación) sí lo es. ¿Estás almacenando la configuración por cliente como parte de tu producto y quieres poder revertirla? Artifacts pueden ser una buena representación de esto.

Estamos encantados de ver a los equipos explorar los casos de uso de Artifacts que no están relacionados con Git, tanto como los centrados en Git.

Artifacts se crean a partir de Durable Objects. La capacidad de crear millones (o decenas de millones+) de instancias de proceso aislado y con estado es inherente al funcionamiento actual de Durable Objects, y eso es exactamente lo que necesitábamos para admitir millones de repositorios Git por espacio de nombres.

Major League Baseball (para la transmisión de partidos en directo), Confluence Whiteboards y nuestro propio SDK de agentes utilizan Durable Objects a gran escala, por lo que estamos desarrollando esto sobre una primitiva que hemos tenido en producción durante algún tiempo.

Sin embargo, lo que sí necesitábamos era una implementación de Git que pudiera ejecutarse en Cloudflare Workers. Tenía que ser pequeño, lo más completo posible, extensible (notes, LFS) y eficiente. Así que creamos uno en Zig y lo compilamos en Wasm.

¿Por qué utilizamos Zig? Tres razones:

1.  Todo el motor del protocolo Git está escrito en Zig puro (sin libc) y compilado en un binario WASM de unos 100 KB (¡con margen para optimizarlo!). Implementa SHA-1, zlib (compresión/descompresión), codificación y decodificación delta, análisis de archivos pack y el protocolo HTTP completo de Git Smart, todo desde cero y sin ninguna dependencia externa aparte de la biblioteca estándar.

2.  Zig nos da control manual sobre la asignación de memoria, lo cual es importante en entornos limitados como Durable Objects. El sistema de compilación Zig nos permite compartir fácilmente el código entre el entorno de ejecución de WASM (producción) y las compilaciones nativas (probando con libgit2 para verificar la corrección).

3. El módulo WASM se comunica con el host JS a través de una interfaz de devolución de llamada ligera: 11 funciones importadas desde el host para operaciones de almacenamiento (host_get_object, host_put_object, etc.) y una para la salida en streaming (host_emit_bytes). La parte de WASM se puede probar por completo de forma aislada.

En el fondo, Artifacts también utiliza R2 (para instantáneas) y KV (para el seguimiento de tokens de autenticación):

^{Cómo funciona Artifacts (Workers, Durable Objects y WebAssembly)}

Un Worker actúa como front-end, gestionando la autenticación y la autorización, las métricas clave (errores, latencia) y buscando cada repositorio de Artifacts (objeto duradero) sobre la marcha. 

En concreto:

• Los archivos se almacenan en la base de datos SQLite del Durable Object subyacente.

  • El almacenamiento de Durable Object tiene un tamaño máximo de fila de 2 MB, por lo que los objetos Git de gran tamaño se dividen en fragmentos y se almacenan en varias filas.

  • Usamos la API de sincronización KV (state.storage.kv)  que en realidad funciona con SQLite.

•  Durable Object tiene límites de memoria de ~128 MB. Esto significa que podemos generar decenas de millones de ellos (son rápidos y ligeros), pero tienen que funcionar dentro de esos límites.

  • Usamos mucho el streaming tanto en la ruta de recuperación como en la de envío, devolviendo directamente un `ReadableStream<Uint8Array>` creado a partir de los fragmentos de salida WASM sin procesar.

  • Evitamos calcular nuestros propios deltas de Git. En su lugar, los deltas sin procesar y los hashes base se conservan junto con el objeto resuelto. En la búsqueda, si el cliente solicitante ya tiene el objeto base, Zig emite el delta en lugar del objeto completo, lo que ahorra ancho de banda y memoria.

• Compatibilidad con v1 y v2 del protocolo git.

  • Admitimos capacidades que incluyen ls-refs, clones superficiales (deepen, deepen-since, deepen-relative) y obtención incremental con negociación have/want.

  • Contamos con un amplio conjunto de pruebas de conformidad para clientes Git y pruebas de verificación para un servidor libgit2, diseñadas para validar la compatibilidad del protocolo.

Además, tenemos soporte nativo para git-notes. Artifacts está diseñado para ser agente primero, y las notas permiten a los agentes añadir notas (metadatos) a los objetos Git. Esto incluye las instrucciones, la atribución del agente y otros metadatos que se pueden leer/escribir desde el repositorio sin mutar los propios objetos.

La mayoría de los repositorios no son tan grandes, y Git está diseñado para ser extremadamente eficiente en términos de almacenamiento. La mayoría de los repositorios tardan solo unos segundos en clonarse como máximo, y eso depende del tiempo de configuración de la red, la autenticación y la suma de comprobación. En la mayoría de los casos con un agente o un entorno de pruebas, eso es factible. Basta con clonar el repositorio al iniciar el entorno de pruebas y ponerse manos a la obra.

Pero, ¿qué pasa con un repositorio de varios GB y/o repositorios con millones de objetos? ¿Cómo podemos clonar ese repositorio rápidamente, sin impedir que el agente se ponga a trabajar durante unos minutos y sin consumir recursos informáticos?

Un marco web popular (¡de 2,4 GB y con un largo historial!) tarda casi 2 minutos en clonarse. Una clonación superficial es más rápida, pero no lo suficiente como para reducir los segundos a un solo dígito, y no siempre queremos omitir el historial (a los agentes les resulta útil).

¿Podemos reducir los repositorios grandes a unos 10-15 segundos para que nuestro agente pueda empezar a trabajar? Bueno, sí: con algunos trucos.

Como parte del lanzamiento de Artifacts, vamos a publicar ArtifactFS como código abierto, un controlador de sistema de archivos diseñado para montar repositorios Git de gran tamaño lo más rápido posible, cargando el contenido de los archivos sobre la marcha en lugar de bloquearse durante la clonación inicial. Es ideal para agentes, entornos aislados, contenedores y otros casos de uso donde el tiempo de inicio es crítico. Si puedes reducir entre 90 y 100 segundos el tiempo de inicio de tu entorno aislado por cada repositorio grande, y ejecutas 10 000 de esos trabajos de entorno aislado al mes, se ahorrarán 2778 horas de espacio aislado.

Puedes pensar en ArtifactFS como "un clon de Git, pero asíncrono":

• ArtifactFS ejecuta una copia sin blobs de un repositorio Git: descarga el árbol de archivos y las referencias, pero no el contenido de los archivos. Puede hacerlo durante el inicio del entorno de pruebas, lo que permite que tu conjunto de herramientas de agente se ponga en marcha.

• En segundo plano, empieza a descargar el contenido del archivo de forma simultánea a través de un daemon ligero.

• Prioriza los archivos en los que los agentes suelen querer operar primero: manifiestos de paquetes (package.json, go.mod), archivos de configuración y código, restando prioridad a los blobs binarios (imágenes, ejecutables y otros archivos que no sean de texto) cuando sea posible para que los agentes puedan escanear el árbol de archivos a medida que se hidratan los propios archivos.

• Si un archivo no está completamente hidratado cuando el agente intenta leerlo, la lectura se bloqueará hasta que lo haga.

El sistema de archivos no intenta "sincronizar" los archivos con el repositorio remoto: con miles o millones de objetos, eso suele ser muy lento, y como estamos hablando de git, no es necesario. Tu agente solo tiene que hacer un commit y un push, como haría con cualquier repositorio. No hay nuevas API que aprender.

Y lo que es más importante, ArtifactFS funciona con cualquier Git remoto, no solo con nuestros propios Artifacts. Si estás clonando repositorios grandes de GitHub, GitLab o una infraestructura Git autoalojada, puedes seguir usando ArtifactFS.

El lanzamiento de hoy es solo la versión beta, y ya estamos trabajando en varias funciones que irán llegando en las próximas semanas:

• Ampliación de las métricas que ofrecemos. Hoy lanzamos métricas para el recuento de operaciones clave por espacio de nombres, repositorio y bytes almacenados por repositorio, para que la gestión de millones de Artifacts no sea complicada.

• Compatibilidad con Suscripciones a eventos para eventos a nivel de repositorio, de modo que podamos emitir eventos en push, pull, clones y forks a cualquier repositorio dentro de un espacio de nombres. Esto también te permitirá recibir eventos, crear webhooks y utilizar esos eventos para notificar a los usuarios finales, gestionar eventos del ciclo de vida dentro de tus productos y/o ejecutar tareas posteriores al envío (como CI/CD).

• SDK de cliente nativos en TypeScript, Go y Python para interactuar con la API de Artifacts

• API de búsqueda a nivel de repositorio y API de búsqueda en todo el espacio de nombres, p. ej. "busca todos los repositorios con un archivo package.json". 

También estamos planeando una API para Workers Builds, que te permitirá ejecutar trabajos de CI/CD en cualquier flujo de trabajo controlado por agente.

Todavía estamos en las primeras etapas con Artifacts, pero queremos que nuestros precios funcionen a escala de agente. Debe ser rentable tener millones de repositorios, los repositorios no utilizados (o rara vez utilizados) no deberían ser un lastre, y nuestros precios deben coincidir con la naturaleza de inquilino único a gran escala de los agentes.

Tampoco deberías tener que pensar en si se va a utilizar un repositorio o no, si está activo o inactivo, y/o si un agente lo va a activar. Te cobraremos por el almacenamiento que consumas y las operaciones (p. ej. clones, bifurcaciones, pushes y pulls) en cada repositorio.

Los repositorios grandes y concurridos costarán más que los repositorios más pequeños y menos utilizados, tanto si tienes 1000, 100 000 o 10 millones de ellos.

También incorporaremos Artifacts al plan Workers gratuito (con algunos límites razonables) a medida que avance la versión beta, y proporcionaremos actualizaciones a lo largo de la versión beta en caso de que cambie este precio y antes de facturar cualquier uso.

Artifacts se lanzará en versión beta privada, y esperamos que la versión beta pública esté lista a principios de mayo (¡en 2026, para ser claros!). En las próximas semanas iremos admitiendo clientes de forma gradual, y puedes inscribirte directamente en la beta privada.

Mientras tanto, puedes obtener más información sobre Artifacts de la siguiente manera:

• Consulta la guía de iniciación en la documentación.

• Visita el panel de control de Cloudflare (Desarrollo > Almacenamiento y bases de datos > Artifacts)

• Consulta los ejemplos de la API REST

• Más información sobre cómo funciona Artifacts por dentro

Sigue el registro de cambios para estar al tanto de cómo avanza la versión beta.