[miniflare] Add local Artifacts binding simulator

src/content/changelog/artifacts/2026-10-14-local-artifacts-development.mdx

@@ -0,0 +1,49 @@
+---
+title: Artifacts now supports local development
+description: Create, import, clone, and push Artifacts repos locally with Wrangler, the Cloudflare Vite plugin, and Workers Vitest.
+products:
+  - artifacts
+  - workers
+date: 2026-10-14
+---
+
+import { TypeScriptExample, WranglerConfig } from "~/components";
+
+You can now develop and test [Artifacts](/artifacts/) locally using `npx wrangler dev`, the [Cloudflare Vite plugin](/workers/vite-plugin/), and the [Workers Vitest integration](/workers/testing/vitest-integration/). Create repos, import Git repositories over HTTPS, issue repo tokens, and clone or push with Git on your machine before deploying to Cloudflare's global network. Local repos are separate from your deployed repos, so you can test changes without affecting production data.
+
+Artifacts bindings now use a local simulator by default:
+
+<WranglerConfig>
+
+```toml
+name = "artifacts-worker"
+main = "src/index.ts"
+compatibility_date = "$today"
+
+[[artifacts]]
+binding = "ARTIFACTS"
+namespace = "default"
+```
+
+</WranglerConfig>
+
+Then use the binding the same way you would in production:
+
+<TypeScriptExample>
+
+```ts
+const created = await env.ARTIFACTS.create("starter-repo");
+
+return Response.json({
+	remote: created.remote,
+	token: created.token,
+});
+```
+
+</TypeScriptExample>
+
+The returned `remote` points to your local dev session, so you can use it with a standard Git client to clone and push.
+
+Local development requires Git 2.32 or later on your `PATH`. If you already use deployed Artifacts during local development, set `remote = true` on the binding to keep that behavior.
+
+To get started, refer to [Local development](/artifacts/guides/local-development/).

src/content/docs/artifacts/api/git-protocol.mdx

@@ -10,9 +10,9 @@ products:
 
 Artifacts exposes Git access for every Artifacts repository.
 
-Each repo has a standard Git smart HTTP remote at `https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/<namespace>/<repo>.git`.
+Each deployed repo has a standard Git smart HTTP remote at `https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/<namespace>/<repo>.git`.
 
-Replace the `<ACCOUNT_ID>` placeholder with your Cloudflare account ID. Use the exact hostname from the repo `remote` returned by the Workers binding or REST API.
+Replace the `<ACCOUNT_ID>` placeholder with your Cloudflare account ID. A local Artifacts binding instead returns an HTTP loopback URL with a dev-session port. Use the exact `remote` returned by the Workers binding or REST API, and refer to [Local development](/artifacts/guides/local-development/) for local setup.
 
 Use the returned repo `remote` with a regular Git client for `clone`, `fetch`, `pull`, and `push`.
 
@@ -27,7 +27,7 @@ Git routes accept repo access tokens in two forms:
 
 ### Token format
 
-Repo tokens are issued in the format `art_v1_<40 hex>?expires=<unix_seconds>`. The `?expires=` suffix is the token's expiry as a unix timestamp in seconds. To check when a token expires, parse the value after `?expires=`.
+Use the complete token returned by Artifacts for Bearer authentication. Tokens include an `?expires=` suffix with their expiry as a Unix timestamp in seconds. Do not assume a fixed token prefix or secret length. For HTTP Basic authentication, use only the portion before `?expires=` as the password.
 
 ### Git `extraHeader` parameter
 

src/content/docs/artifacts/api/workers-binding.mdx

@@ -33,7 +33,7 @@ Add the Artifacts binding to your Wrangler config file:
 [[artifacts]]
 binding = "ARTIFACTS"
 namespace = "default" # replace with your Artifacts namespace
-# remote = true # optional: use the remote Artifacts service in local dev
+# Set remote = true to use deployed Artifacts during local development.
 ```
 
 </WranglerConfig>
@@ -46,7 +46,7 @@ export interface Env {
 }
 ```
 
-Wrangler generates the `Artifacts` type for consumers and binds it directly in your environment.
+Wrangler generates the `Artifacts` type for consumers and binds it directly in your environment. In local development, omitting `remote` or setting `remote = false` uses the local simulator. Set `remote = true` to reach the deployed service. For the local Git prerequisite, storage boundaries, and setup instructions, refer to [Local development](/artifacts/guides/local-development/).
 
 :::note
 

src/content/docs/artifacts/get-started/workers.mdx

@@ -40,10 +40,10 @@ To set up Artifacts manually, follow the steps below.
 
 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`](/workers/wrangler/commands/general/#login) and [Running Wrangler in CI/CD](/workers/ci-cd/).
-- Access to Artifacts in your Cloudflare account.
+- Wrangler installed. Local Artifacts development does not require Cloudflare credentials. Authenticate Wrangler before deploying or using a remote binding.
+- Access to Artifacts in your Cloudflare account for the deployment step.
 - A namespace name, for example `default`.
-- A local `git` client.
+- 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.
 
 ## 1. Create a Worker project
@@ -89,12 +89,12 @@ compatibility_date = "$today"
 [[artifacts]]
 binding = "ARTIFACTS"
 namespace = "default"
-# Set remote = true if you want Wrangler to use the remote Artifacts service in local dev.
+# To use deployed Artifacts during local development, set remote = true.
 ```
 
 </WranglerConfig>
 
-This exposes Artifacts as `env.ARTIFACTS` inside your Worker.
+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](/artifacts/guides/local-development/).
 
 If you are using TypeScript, regenerate your local binding types:
 
@@ -172,19 +172,20 @@ Your Worker will call `env.ARTIFACTS.create()` and return three values you will
 ```json
 {
 	"name": "starter-repo",
-	"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git",
-	"token": "art_v1_0123456789abcdef0123456789abcdef01234567?expires=1760000000"
+	"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 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.
+- `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:
 
 ```sh
 export ARTIFACTS_REMOTE="<PASTE_REMOTE_FROM_RESPONSE>"
-export ARTIFACTS_TOKEN="<PASTE_TOKEN_FROM_RESPONSE>"
+read -rs ARTIFACTS_TOKEN # Paste the token without saving it in your shell history.
+printf '\n'
 ```
 
 	</TabItem>
@@ -207,7 +208,6 @@ 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.
 
-
 ```sh
 mkdir artifacts-demo
 cd artifacts-demo
@@ -221,13 +221,7 @@ git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" push -u origin
 
 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:
-
-```sh
-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
-```
+For other authentication options, refer to [Git protocol](/artifacts/api/git-protocol/).
 
 ## 6. Pull the repo with a regular Git client
 
@@ -241,15 +235,12 @@ 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:
-
-```sh
-git clone "$ARTIFACTS_AUTH_REMOTE" artifacts-clone
-```
+Use the `remote` URL returned by your Worker after each dev-server restart. The local loopback port can change.
 
 ## 7. Deploy your Worker
 
-Switch back to your Worker project directory: 
+Switch back to your Worker project directory:
+
 ```sh
 cd artifacts-worker
 ```
@@ -262,6 +253,12 @@ Wrangler prints your `workers.dev` URL. Use the same `curl` request against that
 
 ## Next steps
 
+<LinkCard
+	title="Local development"
+	href="/artifacts/guides/local-development/"
+	description="Configure local Artifacts, persistence, Git, and explicit remote opt-in."
+/>
+
 <LinkCard
 	title="Workers binding reference"
 	href="/artifacts/api/workers-binding/"

src/content/docs/artifacts/guides/authentication.mdx

@@ -18,7 +18,7 @@ Review [Namespaces](/artifacts/concepts/namespaces/) first, then use one namespa
 
 | Interface | Authenticate with | Permissions or scopes | Use for |
 | --- | --- | --- | --- |
-| Workers binding | Configured `artifacts` binding | Wrangler auth is only for local Wrangler commands such as `dev` and `deploy`. | Worker code that calls `env.ARTIFACTS` |
+| Workers binding | Configured `artifacts` binding | Local simulation needs no Cloudflare credentials. Remote development and deployment require Wrangler authentication. | Worker code that calls `env.ARTIFACTS` |
 | REST API | Cloudflare API token in `Authorization: Bearer ...` | **Artifacts** > **Read** for read routes and **Artifacts** > **Edit** for write routes. | Control-plane HTTP requests |
 | Git protocol | Repo-scoped Artifacts token | `read` for clone, fetch, and pull. `write` for push. | Standard Git over HTTPS |
 
@@ -44,7 +44,7 @@ namespace = "default"
 
 </WranglerConfig>
 
-At runtime, deployed Workers use the configured binding directly. For local Wrangler commands such as `wrangler dev`, `wrangler deploy`, or `wrangler types`, authenticate Wrangler first. For local OAuth authentication, refer to [`wrangler login`](/workers/wrangler/commands/general/#login). For CI or headless environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/).
+At runtime, deployed Workers use the configured binding directly. `wrangler dev` with a local Artifacts binding does not require Cloudflare credentials. To deploy or use `remote = true` during development, authenticate Wrangler. For OAuth authentication, refer to [`wrangler login`](/workers/wrangler/commands/general/#login). For CI or headless environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/). For the local Git prerequisite, refer to [Local development](/artifacts/guides/local-development/).
 
 ## Authenticate the REST API
 

src/content/docs/artifacts/guides/index.mdx

@@ -12,6 +12,6 @@ products:
 
 import { DirectoryListing } from "~/components";
 
-In-depth guides for using Artifacts in production, including how Artifacts authenticates clients, imports existing Git repos, and mounts large repos within sandboxes.
+Guides for local development and deployed Artifacts, including authentication, imports, and mounting large repos within sandboxes.
 
 <DirectoryListing />

src/content/docs/artifacts/guides/local-development.mdx

@@ -0,0 +1,86 @@
+---
+title: Develop with local Artifacts
+description: Use the local Artifacts binding with Wrangler, Vite, or Workers Vitest without accessing your deployed repositories.
+pcx_content_type: how-to
+sidebar:
+  order: 1
+products:
+  - artifacts
+---
+
+import { PackageManagers, Steps, WranglerConfig } from "~/components";
+
+The local Artifacts simulator lets you develop against a Git-compatible repository on your machine. Local repositories and tokens are separate from deployed Artifacts resources. Creating, pushing to, or deleting a local repo does not change a deployed repo.
+
+## Choose a binding mode
+
+When you run a Worker locally, the `artifacts` binding uses the local simulator unless you explicitly set `remote = true`. An omitted `remote` setting and `remote = false` both select local storage. If your existing development workflow relied on an implicit remote binding, set `remote = true` to keep using the deployed service.
+
+| Setting                              | Binding destination        | Local Git installation            | Cloudflare credentials for local development |
+| ------------------------------------ | -------------------------- | --------------------------------- | -------------------------------------------- |
+| Omitted `remote` or `remote = false` | Local simulator            | Required                          | Not required                                 |
+| `remote = true`                      | Deployed Artifacts service | Not required to start the binding | Required                                     |
+
+The local simulator is available through `wrangler dev`, the Cloudflare Vite plugin, and Workers Vitest. It does not provide a local REST API, Artifacts CLI, dashboard, SSH endpoint, or Git LFS server.
+
+## Start local development
+
+<Steps>
+
+1. Install Git 2.32 or newer on your development machine. Make `git` available on the `PATH` of the process that starts your dev server or tests. Verify the version in that environment:
+
+   ```sh
+   git --version
+   ```
+
+   Use an up-to-date, security-patched Git release.
+
+   If Git is unavailable or older than 2.32, local Artifacts fails at startup with installation or upgrade instructions. Restart your dev tool after changing `PATH`. This version requires a globally available Git installation. We plan to open-source a JavaScript Git engine in the future. It is not included in this version. Deployed Artifacts does not require Git on your development machine.
+
+2. Add a binding to your Wrangler config file. If your project already has a binding, leave `remote` unset or set it to `false`:
+
+   <WranglerConfig>
+
+   ```toml title="wrangler.toml"
+   name = "artifacts-worker"
+   main = "src/index.ts"
+   compatibility_date = "$today"
+
+   [[artifacts]]
+   binding = "ARTIFACTS"
+   namespace = "default"
+   ```
+
+   </WranglerConfig>
+
+   The namespace identifies local repositories. It does not import repos from a deployed namespace with the same name.
+
+3. Start the dev server:
+
+   <PackageManagers type="exec" pkg="wrangler" args="dev" />
+
+   Use the same Wrangler config file with the Cloudflare Vite plugin or Workers Vitest. For a Worker example that creates a repo, refer to [Get started with Workers](/artifacts/get-started/workers/).
+
+4. Use the `remote` URL and initial token returned by `env.ARTIFACTS.create()` to clone or push with Git. The local URL uses loopback HTTP and a port selected for this dev session. Get a fresh URL from the binding after restarting the dev server instead of hardcoding the port:
+
+   ```sh
+   git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
+   ```
+
+   Set `ARTIFACTS_REMOTE` to the returned `remote` value and `ARTIFACTS_TOKEN` to the returned token before running this command. The token is a repo credential, not a Cloudflare API token. Keep it out of source files, Git config, and logs. You can also use HTTP Basic auth when Git prompts: enter any username and the repo token as the password.
+
+</Steps>
+
+## Keep or reset local repositories
+
+Local repository metadata and Git objects persist under your dev tool's resource persistence directory. For Wrangler, this is typically `.wrangler/state/` when persistence is on. Use the same project root and persistence settings to keep data across restarts. Turning off persistence, such as with Vite's `persistState: false`, makes the data temporary.
+
+To reset local Artifacts, stop the dev server and back up any repositories you need. Then delete only the `artifacts/` directory inside that tool's resource persistence directory. Do not delete unrelated binding data. Local tokens and repository data do not transfer to a remote binding.
+
+## Use an HTTPS import explicitly
+
+Selecting a local binding never automatically contacts Cloudflare. Calling `env.ARTIFACTS.import()` with an HTTPS source URL is different: Git on your development machine contacts the specified host, including private-network hosts. Only import URLs you trust. Imports do not follow HTTP redirects. Supply the final HTTPS Git URL, especially when using credentials. The source can require credentials or a trusted certificate. To trust a private certificate authority, set `GIT_SSL_CAINFO` in the dev tool's host environment before startup. Do not turn off certificate verification.
+
+A successful local import does not retain URL credentials in repository metadata or the Git configuration. If the process exits during an import, treat any partial local storage as sensitive until you inspect or reset it. Keep import URLs with credentials out of logs. For the binding arguments, refer to [Workers binding](/artifacts/api/workers-binding/#importparams).
+
+To use deployed Artifacts during local development, set `remote = true` on the binding and authenticate your dev tool. The remote binding does not synchronize with the local simulator. For authentication options, refer to [Authentication](/artifacts/guides/authentication/).