Create an Artifacts repo from a Worker and use a standard Git client to push and pull content.
By the end of this guide, you will create a Worker, bind it to Artifacts, create a repo through the Workers binding, push a commit, and clone the same repo back with a standard Git client.
Start by reading Namespaces, then choose the namespace name you will use. This guide uses default in the examples.
Copy this prompt into your coding agent to set up your first Artifacts repository and start pushing code to it.
To set up Artifacts manually, follow the steps below.
- Sign up for a Cloudflare account ↗︎.
- Install
Node.js↗︎.
Node.js version manager
Use Vite+ (vp env) ↗︎ to install and manage Node.js versions.
For supported Node.js versions, refer to the Wrangler system requirements.
You also need:
- Wrangler installed. You do not need Cloudflare credentials to develop with Artifacts locally. Authenticate Wrangler before you deploy or use a remote binding. For local OAuth authentication or CI setup, refer to
wrangler loginand Running Wrangler in CI/CD. - Access to Artifacts on the Workers Paid plan for the deployment step.
- A namespace name, for example
default. - Git 2.32 or newer installed on your development machine and available on
PATH. The local simulator checks the Git version at startup. jq, if you want to extract response fields automatically.
-
Create a new Worker project with C3:
npm create cloudflare@latest -- artifacts-workeryarn create cloudflare artifacts-workerpnpm create cloudflare@latest artifacts-workerFor setup, select the following options:
- For What would you like to start with?, choose
Hello World example. - For Which template would you like to use?, choose
Worker only. - For Which language do you want to use?, choose
TypeScript. - For Do you want to use git for version control?, choose
Yes. - For Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?, choose
Yes. - For Do you want to deploy your application?, choose
No(we will be making some changes before deploying).
- For What would you like to start with?, choose
-
Move into the project directory:
cd artifacts-worker
Open your Wrangler config file and add the Artifacts binding:
{
"$schema": "./node_modules/wrangler/config-schema.json",
"name": "artifacts-worker",
"main": "src/index.ts",
"upload_source_maps": true,
// Set this to today's date
"compatibility_date": "2026-11-16",
"artifacts": [
{
"binding": "ARTIFACTS",
"namespace": "default"
}
]
}name = "artifacts-worker"
main = "src/index.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-11-16"
[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"
# To use deployed Artifacts during local development, set remote = true.This exposes Artifacts as env.ARTIFACTS inside your Worker. During local development, an omitted remote setting uses local storage. Set remote = true only if you want to use deployed Artifacts. Local and deployed repos do not synchronize. For prerequisites, persistence, and migration from implicit remote bindings, refer to Local development.
If you are using TypeScript, regenerate your local binding types:
npx wrangler typesyarn wrangler typespnpm wrangler typesWrangler adds an Artifacts type to your generated worker-configuration.d.ts file.
Replace src/index.ts with the following code:
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (request.method === "POST" && url.pathname === "/repos") {
// Read the repo name from the request body so the route is reusable.
const body = await request.json().catch(() => ({}));
const repoName = body.name ?? "starter-repo";
// Create the repo and return the remote URL plus initial write token.
const created = await env.ARTIFACTS.create(repoName);
return Response.json({
name: created.name,
remote: created.remote,
token: created.token,
});
}
return new Response("Use POST /repos to create an Artifacts repo.", {
status: 405,
headers: { Allow: "POST" },
});
},
};export default {
async fetch(request, env) {
const url = new URL(request.url);
if (request.method === "POST" && url.pathname === "/repos") {
// Read the repo name from the request body so the route is reusable.
const body = await request.json().catch(() => ({}));
const repoName = body.name ?? "starter-repo";
// Create the repo and return the remote URL plus initial write token.
const created = await env.ARTIFACTS.create(repoName);
return Response.json({
name: created.name,
remote: created.remote,
token: created.token,
});
}
return new Response("Use POST /repos to create an Artifacts repo.", {
status: 405,
headers: { Allow: "POST" },
});
},
};This Worker creates an Artifacts repo and returns the remote URL and token your Git client needs to push and pull.
For the demo, the Worker returns the initial write token. In production, mint short-lived read tokens for clone and pull flows, and mint write tokens only for operations that need push access.
Start local development:
npx wrangler devyarn wrangler devpnpm wrangler devThen, open a second terminal and send a request to your Worker to create a new Artifacts repo:
curl http://localhost:8787/repos \
--header "Content-Type: application/json" \
--data '{
"name": "starter-repo"
}'Your Worker will call env.ARTIFACTS.create() and return three values you will need for Git operations:
{
"name": "starter-repo",
"remote": "http://127.0.0.1:<PORT>/git/default/starter-repo.git",
"token": "<REPO_TOKEN>"
}name: the repo name. Must be unique within the namespace.remote: the local Git URL. Use the returned port rather than copying the placeholder. A deployed Worker instead returns an HTTPS URL for your account.token: a repo-scoped credential for Git operations. Keep its full value private.
Copy the remote and token values into local shell variables:
export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_RESPONSE>"
read -rs ARTIFACTS_TOKEN # Paste the token without saving it in your shell history.
printf '\n'RESPONSE=$(curl --silent http://localhost:8787/repos \
--header "Content-Type: application/json" \
--data '{"name":"starter-repo"}')
export ARTIFACTS_REMOTE=$(printf '%s' "$RESPONSE" | jq -r '.remote')
export ARTIFACTS_TOKEN=$(printf '%s' "$RESPONSE" | jq -r '.token')In the previous step, your Worker created an empty Artifacts repo. Now you will create a local Git repo, add a file, and push it to Artifacts — the same way you would push to any Git remote.
mkdir artifacts-demo
cd artifacts-demo
git init -b main
printf '# Artifacts demo\n' > README.md
git add README.md
git commit -m "Initial commit"
git remote add origin "$ARTIFACTS_REMOTE"
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin mainThe -c http.extraHeader flag passes the token as a request header, which keeps it out of your Git config and shell history.
For other authentication options, refer to Git protocol.
Clone the same repo into a second directory:
cd ..
git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
git -C artifacts-clone log --oneline -1You should see the commit you pushed in the previous step.
The local Git port is saved with your local state and reused after a dev-server restart. If it changes because another process took it, use the new remote URL returned by your Worker.
Switch back to your Worker project directory:
cd artifacts-workerDeploy the Worker so you can create repos without running wrangler dev:
npx wrangler deployyarn wrangler deploypnpm wrangler deployWrangler prints your workers.dev URL. Use the same curl request against that URL to create additional repos from production.