1# Artifacts Configuration
2 
3## Worker Binding
4 
5Configure the `artifacts` binding in your Wrangler config:
6 
7```toml
8[[artifacts]]
9binding = "ARTIFACTS"
10namespace = "default"
11```
12 
13This exposes Artifacts on `env.ARTIFACTS` inside your Worker.
14 
15If you authenticate with `wrangler login`, current docs say Wrangler requests `artifacts:write` by default.
16 
17## TypeScript
18 
19Regenerate Worker types after adding the binding:
20 
21```bash
22npx wrangler types
23```
24 
25Use the generated binding type in your environment definition:
26 
27```typescript
28interface Env {
29  ARTIFACTS: Artifacts;
30}
31```
32 
33Wrangler generates the `Artifacts` type from the binding. Treat the generated `worker-configuration.d.ts` file as the source of truth for your environment.
34 
35## Structure Repos for Isolation
36 
37Artifacts works best when autonomous work is isolated:
38- Create one repo per agent, session, sandbox, or task when work should stay separate.
39- Fork from a reviewed baseline instead of copying starter files into every new repo.
40- Use branches only when collaborators share the same lifecycle and need to work in one repo.
41- Use namespaces to separate environments, teams, or high-rate workloads.
42 
43## REST Configuration
44 
45For external systems, configure the namespace-scoped base URL and gateway JWT:
46 
47```bash
48export ARTIFACTS_NAMESPACE="default"
49export ARTIFACTS_JWT="<YOUR_GATEWAY_JWT>"
50export ARTIFACTS_BASE_URL="https://artifacts.cloudflare.net/v1/api/namespaces/$ARTIFACTS_NAMESPACE"
51```
52 
53Some environments also expose an `/edge/v1/api/...` base path. Verify the correct host and base path in the live docs for your Artifacts environment.
54 
55Use environment variables or your secret manager. Do not hardcode gateway JWTs or repo tokens.
56 
57## Repo Tokens
58 
59Artifacts workflows usually involve repo-scoped tokens returned by `create()` or minted later through the binding or REST API.
60 
61Keep the control plane and data plane separate:
62- Use the **Workers binding** or **REST API** with a gateway JWT to create repos and mint tokens.
63- Use repo-scoped tokens only for **Git operations** against the returned `remote`.
64 
65Recommended handling:
66- Mint the narrowest scope you need: `read` or `write`
67- Prefer short-lived tokens for handoff between systems
68- Revoke tokens that are no longer needed
69 
70Verify the current token behavior and auth guidance in `https://developers.cloudflare.com/artifacts/` before building long-lived automation.
71 
72## Git Consumers
73 
74Artifacts is designed to work with standard git-over-HTTPS clients once you have a repo `remote` and an access token.
75 
76Prefer header-based auth for local tooling so the full token stays out of the remote URL:
77 
78```bash
79git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
80```
81 
82Use a Basic-auth remote only for short-lived commands that need a self-contained URL.
83 
84## Retrieval Checklist
85 
86Check the live docs before relying on:
87- the current Workers binding surface
88- exact token formats
89- availability or product status
90- route details for import, fork, and token-management flows
91- the correct control-plane host or `/edge/v1` base path for your environment
92- platform limits or pricing
93