Skip to content

SYSTEM Cited by 1 source

Cloudflare Artifacts

Cloudflare Artifacts (blog.cloudflare.com/artifacts-git-for-agents-beta, developers.cloudflare.com/artifacts) is Cloudflare's distributed, versioned filesystem, built for agents, that speaks the Git wire protocol. Announced 2026-04-16 in private beta; public beta planned for early May 2026. Each Artifacts repository is a bare Git repo, created programmatically via a REST API or a native Workers binding, and accessible from any regular Git client over an authenticated HTTPS remote URL.

Role

Versioned storage primitive for agent workloads where every session / sandbox / customer / fork wants its own isolated history-preserving workspace. Cloudflare frames the need as agent-scale:

"Developers and agents are generating more code than ever — more code will be written over the next 5 years than in all of programming history — and it's driven an order-of-magnitude change in the scale of the systems needed to meet this demand. Source control platforms are especially struggling here: they were built to meet the needs of humans, not a 10x change in volume driven by agents who never sleep, can work on several issues at once, and never tire." — Artifacts launch post

Positioning is explicit about non-source-control use cases: per-session agent state (filesystem + prompt history), per-customer config with rollback / diff, per-sandbox workspaces that need fork / time-travel / diff semantics on arbitrary data. See concepts/repo-per-agent-session.

Why speak Git? — patterns/git-protocol-as-api

The load-bearing design decision. From the post:

"Agents know Git. It's deep in the training data of most models. The happy path and the edge cases are well known to agents, and code-optimized models (and/or harnesses) are particularly good at using git."

"We could have invented an entirely new, bespoke protocol… but then you have the bootstrap problem. AI models don't know it, so you have to distribute skills, or a CLI, or hope that users are plugged into your docs MCP… all of that adds friction. If we can just give agents an authenticated, secure HTTPS Git remote URL and have them operate as if it were a Git repo, though? That turns out to work pretty well."

For non-Git-speaking clients — Workers, Lambda, Node — Cloudflare exposes a REST API plus forthcoming native SDKs; isomorphic-git also works. See concepts/agent-first-storage-primitive.

Architecture

Storage stratification — patterns/do-backed-git-server

One Durable Object per repo. A front-end Worker handles auth, metrics, and DO lookup per request. R2 holds pack-file snapshots; KV tracks auth tokens.

client ─ HTTPS ─▶ Worker ─▶ Durable Object (per-repo)
                   │            │
                   │            ├── embedded SQLite (chunked git objects)
                   │            └── Zig WASM git server (~100 KB)
                   │
                   ├── R2  (pack-file snapshots)
                   └── KV  (auth tokens)

Specifics from the post:

  • Files stored in the DO's SQLite via the state.storage.kv sync API. DO storage's 2 MB max row size means large Git objects are chunked and stored across multiple rows.
  • ~128 MB DO memory limit drives heavy use of streaming on both the fetch and push paths; the Worker returns a ReadableStream<Uint8Array> built directly from the raw WASM output chunks.
  • Delta-form alongside resolved object: "We avoid calculating our own git deltas, instead, the raw deltas and base hashes are persisted alongside the resolved object. On fetch, if the requesting client already has the base object, Zig emits the delta instead of the full object, which saves bandwidth and memory." Subtler than vanilla pack files — both forms live side by side rather than one being derived on demand.
  • Both v1 and v2 of the Git smart-HTTP protocol supported including ls-refs, shallow clones (deepen, deepen-since, deepen-relative), and incremental fetch with have/want negotiation.

A Git server in ~100 KB of Wasm — concepts/wasm-git-server

The Git-protocol engine is a ~100 KB pure-Zig WASM binary with zero dependencies beyond std. Implements SHA-1, zlib inflate/deflate, delta encoding/decoding, pack parsing, and the full smart-HTTP protocol — all from scratch. Three reasons Zig given in the post:

  1. "The entire git protocol engine is written in pure Zig (no libc), compiled to a ~100KB WASM binary (with room for optimization!)."
  2. "Zig gives us manual control over memory allocation which is important in constrained environments like Durable Objects. The Zig Build System lets us easily share code between the WASM runtime (production) and native builds (testing against libgit2 for correctness verification)."
  3. "The WASM module communicates with the JS host via a thin callback interface: 11 host-imported functions for storage operations (host_get_object, host_put_object, etc.) and one for streaming output (host_emit_bytes). The WASM side is fully testable in isolation."

Extensive conformance test suite against real Git clients + verification against libgit2 as a cross-implementation oracle.

API surface

REST / Workers binding

// Create a repo
const repo = await env.AGENT_REPOS.create(name)
return { repo.remote, repo.token }

Gives the agent / harness a token-authenticated HTTPS remote URL of the shape:

https://x:${TOKEN}@<namespace-id>.artifacts.cloudflare.net/git/<repo>.git

import() — bootstrap from any Git remote

const { remote, token } = await env.ARTIFACTS.import({
  source: { url: "https://github.com/cloudflare/workers-sdk", branch: "main" },
  target: { name: "workers-sdk" },
})

fork() — isolated copy for review / debugging / branching an agent session

const repo = await env.ARTIFACTS.get("workers-sdk")
const fork = await repo.fork("workers-sdk-review", { readOnly: true })

"Want to create 10,000 forks from a known-good starting point? You guessed it: Artifacts again." Positioned as a first-class debugging / collaboration primitive — "Send a URL and fork it. Want to riff on an API? Have a co-worker fork it and pick up from where you left off."

git-notes — native metadata for agents

"Artifacts is designed to be agent-first, and notes enable agents to add notes (metadata) to Git objects. This includes prompts, agent attribution and other metadata that can be read/written from the repo without mutating the objects themselves." Notes sit beside the tree without changing commit hashes — so LLM annotations (prompt / model / judge verdict) don't invalidate downstream signatures or attestations.

Dogfood use: Cloudflare's internal agents

"Inside Cloudflare, we're using Artifacts for our internal agents: automatically persisting the current state of the filesystem and the session history in a per-session Artifacts repo. This enables us to:

  • Persist sandbox state without having to provision (and keep) block storage around.
  • Share sessions with others and allow them to time-travel back through both session (prompt) state and file state, irrespective of whether there were commits to the "actual" repository (source control).
  • And the best: fork a session from any point, allowing our team to share sessions with a co-worker and have them pick it up from them."

Canonical wiki instance of agent memory at the filesystem + session-history tier, complementary to [[systems/ project-think|Project Think]]'s DO-SQLite conversation-tree memory and AI Search's per-tenant-index semantic memory. Three different memory substrates, each with different access patterns, all on the same DO-as-actor foundation.

ArtifactFS — sibling open-source FS driver

Cloudflare simultaneously released ArtifactFS (github.com/cloudflare/artifact-fs), a client-side filesystem driver that mounts a Git repo with blobless-clone-plus-background-hydration semantics — "git clone but async". Works against any Git remote, not just Artifacts. See concepts/async-clone-hydration, patterns/blobless-clone-lazy-hydrate.

Pricing

$/unit Included
Operations $0.15 per 1,000 operations First 10 k / month
Storage $0.50/GB-month First 1 GB

Workers Free-plan availability planned during the beta. "Big, busy repos will cost more than smaller, less-often-used repos, whether you have 1,000, 100,000, or 10 million of them." Same concepts/scale-to-zero economics as the rest of the Cloudflare agent stack — unused repos aren't a drag; no hot/cold tiers.

Roadmap (from the post)

  • Expanded per-namespace / per-repo metrics.
  • Event Subscriptions for repo-level push / pull / clone / fork events; drives webhooks, end-user notifications, lifecycle events, post-push jobs (CI/CD).
  • Native TypeScript / Go / Python SDKs.
  • Repo-level + namespace-wide search APIs ("find all the repos with a package.json file").
  • A Workers Builds API for running agent-driven CI/CD on Artifacts repos.

Seen in

Last updated · 200 distilled / 1,178 read