Workers (2)

Workers (2)

Last updated Oct 22, 2026 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.

Set up with your coding agent

Copy this prompt into your coding agent to set up your first Artifacts repository and start pushing code to it.

Copy promptPrompt copied!

To set up Artifacts manually, follow the steps below.

Prerequisites

Sign up for a Cloudflare account ↗︎.
Install Node.js ↗︎.

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

You also need:

Wrangler installed. If you use local Wrangler commands in this guide, authenticate Wrangler first. For local OAuth authentication or CI setup, refer to wrangler login and Running Wrangler in CI/CD.
Access to Artifacts on the Workers Paid plan.
A namespace name, for example default.
A local git client.
jq, if you want to extract response fields automatically.

1. Create a Worker project

Create a new Worker project with C3:npmyarnpnpm

npm create cloudflare@latest -- artifacts-worker

yarn create cloudflare artifacts-worker

pnpm create cloudflare@latest artifacts-worker

For 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). 2. Move into the project directory:

sh cd artifacts-worker

2. Add the Artifacts binding

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-10-27",
  "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-10-27"

[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"
# Set remote = true if you want Wrangler to use the remote Artifacts service in local dev.

This exposes Artifacts as env.ARTIFACTS inside your Worker.

If you are using TypeScript, regenerate your local binding types:

npmyarnpnpm

npx wrangler types

yarn wrangler types

pnpm wrangler types

Wrangler adds an Artifacts type to your generated worker-configuration.d.ts file.

3. Write your Worker

Replace src/index.ts with the following code:

src/index.jsjs

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" },
        });
    },
};

src/index.tsts

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.

Protect token-issuing routes

This example omits authentication so it can focus on the Artifacts flow. In production, authorize the caller before creating repos or returning write tokens.

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.

4. Invoke your Worker to create a repo

Start local development:

npmyarnpnpm

npx wrangler dev

yarn wrangler dev

pnpm wrangler dev

Then, 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": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git",
    "token": "art_v1_0123456789abcdef0123456789abcdef01234567?expires=1760000000"
}

name: the repo name. Must be unique within the namespace.
remote: the Git remote URL for this repo. <ACCOUNT_ID> will be your actual Cloudflare account ID.
token: a short-lived credential for Git operations. The token encodes its expiry directly in the ?expires= suffix as a Unix timestamp.

Copy the remote and token values into local shell variables:

export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_RESPONSE>"
export ARTIFACTS_TOKEN="<PASTE_TOKEN_FROM_RESPONSE>"

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')

5. Push your first commit with git

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 main

The -c http.extraHeader flag passes the token as a request header, which keeps it out of your Git config and shell history.

If you need a self-contained remote URL for a short-lived command, build one from the token secret instead:

export ARTIFACTS_TOKEN_SECRET="${ARTIFACTS_TOKEN%%\?expires=*}"
export ARTIFACTS_AUTH_REMOTE="https://x:${ARTIFACTS_TOKEN_SECRET}@${ARTIFACTS_REMOTE#https://}"
git push "$ARTIFACTS_AUTH_REMOTE" HEAD:main

6. Pull the repo with a regular Git client

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 -1

You should see the commit you pushed in the previous step.

You can also clone with a self-contained remote URL for a short-lived command:

git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone

7. Deploy your Worker

Switch back to your Worker project directory:

cd artifacts-worker

Deploy the Worker so you can create repos without running wrangler dev:

npmyarnpnpm

npx wrangler deploy

yarn wrangler deploy

pnpm wrangler deploy

Wrangler prints your workers.dev URL. Use the same curl request against that URL to create additional repos from production.

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/artifacts/get-started/workers/#page","headline":"Workers","description":"Create an Artifacts repo from a Worker.","url":"https://developers.cloudflare.com/artifacts/get-started/workers/","inLanguage":"en","image":"https://developers.cloudflare.com/artifacts/get-started/workers/og.png?v=880a8c41de9190da","dateModified":"2026-10-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Mount large repos without waiting for full clones. title: ArtifactFS image: https://developers.cloudflare.com/artifacts/guides/artifact-fs/og.png?v=6d16e36f91303f8b

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/artifacts/llms.txt
Use this file to discover all available pages before exploring further.

Workers (2)

Workers (2)

Set up with your coding agent

Prerequisites

1. Create a Worker project

2. Add the Artifacts binding

3. Write your Worker

4. Invoke your Worker to create a repo

5. Push your first commit with git

6. Pull the repo with a regular Git client

7. Deploy your Worker

Next steps

Workers binding reference

Best practices

Git protocol

On this page