1# Cloudflare Artifacts
2 
3Store versioned file trees behind a repo-style interface that works from Workers, the REST API, and Git-compatible tooling.
4 
5## Overview
6 
7Use **Artifacts** when the thing you need to store is a versioned filesystem tree rather than a single object, key, or SQL row.
8 
9Typical Artifacts use cases:
10- Git-style repositories
11- Per-agent, per-session, or per-task repos
12- Build outputs and deployment bundles
13- Checkpoints and generated assets
14- Shared file trees passed between developer tools and Workers
15 
16Artifacts is a good fit when the same content needs to be addressable from **Workers**, the **REST API**, and **Git-compatible clients**.
17 
18Artifacts is especially useful for agent and automation workflows where each unit of work should have its own isolated repo and token.
19 
20**Prefer retrieval over memory** for current availability, authentication details, route shapes, limits, and pricing. Start at `https://developers.cloudflare.com/artifacts/`.
21 
22## When to Use Artifacts
23 
24| Need | Use | Why |
25|------|-----|-----|
26| Versioned file trees such as repos, build outputs, checkpoints, or generated assets | Artifacts | Artifacts stores and shares **versioned filesystem content** |
27| A git-compatible workflow with `clone`, `fetch`, `pull`, or `push` | Artifacts | Artifacts exposes **git-over-HTTPS remotes** and repo-scoped tokens |
28| The same artifact accessible from Workers, HTTP APIs, and developer tooling | Artifacts | Artifacts is available through a **Workers binding**, **REST API**, and **git-compatible interface** |
29| Large files by object key, app config by key, or relational app data | R2, KV, or D1 | Use storage products directly when you need **objects, key-value entries, or SQL rows**, not versioned file trees |
30 
31## Recommended Workflow
32 
33- Create one repo per agent, session, user workspace, or task when work should stay isolated.
34- Fork from a stable baseline when many repos need the same starter files or prompts.
35- Use branches only when collaborators share the same lifecycle and need to work in one repo.
36- Use namespaces to separate environments, teams, or high-rate workloads.
37 
38## Quick Start
39 
40**From a Worker:**
41 
42```typescript
43interface Env {
44  ARTIFACTS: Artifacts;
45}
46 
47const created = await env.ARTIFACTS.create("starter-repo");
48// created.remote -> git remote URL
49// created.token -> initial repo token
50```
51 
52**From the REST API:**
53 
54Use the namespace-scoped Artifacts base URL plus a gateway JWT. For imports from existing HTTPS remotes, use the REST API rather than the Workers binding.
55 
56## Reading Order
57 
58| Task | Read |
59|------|------|
60| Decide whether Artifacts is the right product | README only |
61| Create or manage repos from a Worker | README → configuration.md → api.md |
62| Integrate Artifacts from an external system | README → api.md |
63| Set up agent or sandbox workflows | README → configuration.md |
64| Verify exact auth, routes, limits, or pricing | Live docs first: `https://developers.cloudflare.com/artifacts/` |
65 
66## In This Reference
67 
68- **[api.md](api.md)** - Workers binding methods, REST routes, token and repo operations
69- **[configuration.md](configuration.md)** - Wrangler binding shape, Worker typing, REST configuration guidance
70 
71## See Also
72 
73- [Cloudflare Artifacts Docs](https://developers.cloudflare.com/artifacts/)
74- [Artifacts Git Protocol Docs](https://developers.cloudflare.com/artifacts/api/git-protocol/)
75- [ArtifactFS Docs](https://developers.cloudflare.com/artifacts/api/artifactfs/)
76- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
77- [Cloudflare Durable Objects Docs](https://developers.cloudflare.com/durable-objects/)
78- [Cloudflare R2 Docs](https://developers.cloudflare.com/r2/)
79- [Cloudflare D1 Docs](https://developers.cloudflare.com/d1/)
80