Skip to content

CONCEPT Cited by 1 source

Local-remote parity

Local-remote parity is the design goal of making local development mirror the production cloud API at the API shape level, not just at the runtime-behavior level. Under strict parity, the same endpoints, request bodies, response bodies, and error shapes exist locally as remotely; the only observable difference is which host serves the request (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare).

Why it matters

Teams with popular local emulators (LocalStack for AWS, Miniflare for Cloudflare, Firebase emulator, Stripe test mode) routinely see a parity gap — the emulator runs the user's code, but the API surface for managing resources (create bucket, seed table, list records) diverges from production. Users maintain two mental models.

Agents suffer more from the parity gap than humans do. A human can look at two slightly-different APIs and reconcile; an agent's plan assumes the API it learned is the one available. The canonical failure mode cited by Cloudflare:

"If an agent thinks it's modifying a remote database, but is actually adding records to local database, and the developer is using remote bindings to develop locally against a remote database, their agent won't understand why the newly-added records aren't showing up when the agent makes a request to the local dev server."

Design requirements

Strict local-remote parity requires:

  1. Same API shape — endpoints, request / response bodies, errors, pagination, streaming semantics all identical.
  2. Same code-gen origin — both the remote API and the local mirror derive from one schema, so they can't drift. See concepts/unified-interface-schema.
  3. Explicit local/remote signaling in output — every CLI command, every log line should make clear which tier it ran against.
  4. Same tooling access — the same CLI, SDKs, MCP server should address both tiers identically, with the only difference being a --local flag or equivalent.
  5. Bidirectional introspection — list / get should work the same way on a local namespace as on a remote one.

Cloudflare's implementation

Cloudflare ships local-remote parity by exposing a local mirror of the Cloudflare API at /cdn-cgi/explorer/api on any Wrangler- or Vite-plugin-powered app (the Local Explorer API). That mirror is wired into the new cf CLI: --local simply routes the command there instead of to Cloudflare's edge. Every other flag and argument behaves identically. Agents pointed at the local URL can manage local Miniflare state the same way they'd manage production.

Pattern shape

See patterns/local-mirror-of-remote-api for the concrete pattern Cloudflare uses to implement parity.

Seen in

Last updated · 200 distilled / 1,178 read