Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- Local mode requires Git 2.32 or later. Wrangler, the Vite plugin and the Vitest plugin each have minimum supported versions.
- With current versions, an omitted remote setting or false selects local storage. Setting true uses the deployed service and requires Cloudflare authentication.
- Vite 1.x and the deprecated vitest-pool-workers package retain earlier remote defaults; current-version behavior must not be assumed for them.
- Local delivery supports only certain repository lifecycle and token events. It excludes push, clone and fetch events and does not retry failed delivery.
Check Git and the development tool you actually use
Cloudflare announced local development support for Artifacts on November 16, 2026. Artifacts is a Git-compatible repository storage service. Its local simulator gives a Worker separate repositories on the development machine; creating, pushing to or deleting a local repository does not change a deployed one.
Check Git in the same terminal, container or remote development environment that starts the server or tests. Git 2.32 or later must be on that process’s PATH. Installing Git on the host does not establish that a container or editor-launched process can find it. Restart the development tool after changing PATH.
The tool minimums are Wrangler 4.163.0, Cloudflare Vite plugin 2.0.0-rc.0, or @cloudflare/vitest-plugin 1.8.3, respectively, or later versions. Check the entry point the project uses; this guide does not require adopting all three. If Git is missing or too old, local Artifacts fails at startup with installation or upgrade instructions.
Check Git in the current environment
shellgit --version
Missing deployed repositories? Check the binding mode
For the current versions above, an omitted remote setting or remote = false selects the local simulator. That local binding does not require Cloudflare credentials. Setting remote = true uses the deployed Artifacts service and requires the development tool to authenticate with Cloudflare. It operates on real remote resources, so it is not a solution when the goal is local isolation.
In an existing Wrangler TOML configuration, explicitly select local mode for the relevant binding. The example is a fragment: retain the project’s entry point, compatibility date and other settings. If ARTIFACTS already exists, edit that entry rather than adding a duplicate. Using the same namespace name does not import repositories from the deployed namespace. Local and remote modes do not sync automatically.
When remote is omitted, wrangler dev, getPlatformProxy() and the Vite plugin warn that the binding uses the local simulator by default. Setting false keeps local mode and silences that warning. In cloudflare.config.ts, the corresponding setting is dev: { remote }.
Cloudflare Vite plugin 1.x is an exception: with remote bindings enabled, an omitted remote still uses deployed repositories. Set false explicitly for local mode. The deprecated @cloudflare/vitest-pool-workers package also retains the earlier remote default and fails without Cloudflare credentials. For local tests, migrate to the current @cloudflare/vitest-plugin and check its configuration.
Local binding fragment for an existing Wrangler TOML file
text[[artifacts]]
binding = "ARTIFACTS"
namespace = "default"
remote = false
Start development and use the returned local remote and repo token
Use the existing development entry point in an established Worker project. A Wrangler project can start its server from the project root with the command below. It starts local development rather than a production deployment. Vite and Workers Vitest projects use their own existing entry points and corresponding configuration.
After creating a repository through env.ARTIFACTS.create(), use its returned remote URL and initial token for standard Git clone or push operations. The local URL uses loopback HTTP and points to the development machine. The token is a repository credential, not a Cloudflare API token. Keep it out of source files, Git configuration and logs.
The local binding’s lack of a Cloudflare credential requirement applies only to its simulator mode. It does not make every other Worker binding, HTTPS repository import or external request work offline. Check the relevant deployed-service documentation and account terms for plan eligibility, fees and regional availability; local-mode instructions do not establish those conditions.
Start the server in an existing Wrangler project
shellnpx wrangler dev
Why does a successful push not start a local Workflow?
The current local simulator does not publish push, clone or fetch events. A Workflow that builds or deploys on a push event therefore does not start locally. Check the event type first; a successful Git push does not establish that the complete event-driven process has been verified.
Local events cover repository creation, import, fork and deletion, plus repository token creation and revocation. Creating, importing or forking a repository also emits a creation event for its initial token. Targets must be Workflows defined by the same Worker. Local delivery supports Workflows, not Queues. Vite plugin 1.x cannot yet start Workflows from local events.
Events are delivered after the repository change completes, with no ordering guarantee. Failed delivery is logged without retries and does not fail an already successful repository operation. Check the repository operation and Workflow instance separately. Declaring events in cloudflare.config.ts requires cf 1.0.0-rc.0 or later, or @cloudflare/config 1.0.0-rc.0 or later when imported directly.
Troubleshoot missing state after restart and failed HTTPS imports
Check the project root and persistence settings first. With persistence enabled, Wrangler and Vite 1.x normally store state under .wrangler/state/; Vite 2.x uses .cloudflare/state/. Setting persistState: false uses temporary state. A directory, configuration or temporary-mode change does not establish that a deployed repository was deleted.
To reset local data, stop the development server and preserve any repositories you need, then handle only the artifacts/ subdirectory under the relevant state path. Do not delete other bindings’ state just to clear Artifacts, or apply a local cleanup procedure to the deployed service.
HTTPS imports run Git on the development machine, which must be able to reach the source repository. Use a trusted repository’s final HTTPS Git URL: imports do not follow HTTP redirects. For an internal Git service with a private CA, set GIT_SSL_CAINFO to a trusted CA file before starting the development process. Do not disable TLS certificate validation to hide a certificate-chain problem.
Sources
Frequently Asked Questions
Can local development use the Artifacts REST API, CLI, SSH or Git LFS?
The current 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. Do not assume deployed-service access methods work locally.
An existing clone cannot connect after restart. Must I recreate the repository?
Check the port first. The development server saves the local Git port with its state and reuses it after restart. If another process has taken that port, it chooses a new one. Get the current remote from the binding and update the existing clone’s origin URL. A connection failure alone is not a reason to recreate the repository.
Can a local repository accept a single file of any size?
No. The current local simulator rejects pushes containing a single file larger than 32 MiB. Reading a larger file produces MEMORY_LIMIT. This is a local simulator limit, not evidence of the storage or billing rules for every deployed plan.