Skip to content

PATTERN Cited by 1 source

Local mirror of remote API

Serve the same API shape locally that your cloud serves remotely, so every client (CLI, SDK, MCP server, agent) can address local-dev resources with the same code that addresses production (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare).

Problem

Local-dev emulators (LocalStack, Miniflare, Firebase emulator, Stripe test mode, etc.) typically focus on running the user's code locally. They are less good at making the management API for resources look the same locally as remotely. Teams end up with:

  • Different code paths in test vs prod to create / seed / reset resources.
  • A parity gap that surfaces as "works locally, fails in prod" or vice-versa.
  • Agents that don't know whether they're looking at real or local data.
  • Tooling fragmentation: production uses aws s3 cp, local uses a custom shell script.

The cost goes up with agents. A human can reconcile two nearly-identical APIs; an agent's plan assumes the one API it knows is the one available, and gets confused when output doesn't match what it wrote. See concepts/local-remote-parity.

Pattern

Expose a local HTTP server that speaks the same API as the production cloud — same endpoints, same request bodies, same response bodies, same errors — and mount it inside the developer's local environment. The same CLI / SDK / MCP / agent pointed at http://localhost:…/cdn-cgi/explorer/api talks to local state; pointed at https://api.cloudflare.com talks to production. Nothing else changes.

Shape:

  1. Local mirror endpoint: well-known path inside the local dev server. Cloudflare uses /cdn-cgi/explorer/api — any Wrangler or Vite plugin powered app gets it for free.
  2. Same schema, same OpenAPI spec: the mirror's OpenAPI is the remote API's OpenAPI. Agents discover the mirror at the local URL and get the same tools.
  3. Backed by emulator state: on-disk state for KV / R2 / object stores; local SQLite for D1-style databases; etc. The mirror is the CRUD layer on top of local Miniflare resources.
  4. Single flag switches tier: --local on the CLI (or equivalent env var / config) routes every command to the mirror. All other flags / args behave identically.
  5. Explicit signaling: every response indicates it came from the local mirror (header, field, or UI hint) so humans and agents know which tier they're on.

Concrete implementation at Cloudflare

  • Local Explorer exposes the API at /cdn-cgi/explorer/api on any Wrangler- or Vite-plugin-powered app.
  • Covers KV, R2, D1, Durable Objects, Workflows — the bindings Miniflare already simulates.
  • OpenAPI spec hosted at the same path for agent discovery.
  • cf CLI uses the mirror when the user passes --local.
  • GUI on top of the mirror (keyboard e in wrangler dev) lets humans seed, inspect, reset local state; the mirror is the API; the GUI is one client of it.

Why it scales

  • Once a service has a unified schema (concepts/unified-interface-schema), generating a local mirror handler is just another code-gen target — the schema already describes every endpoint.
  • Agents can discover the local mirror the same way they discover remote: one OpenAPI URL.
  • Existing CLI / SDK / MCP code paths reuse directly; no local-specific variants.

Risks / tradeoffs

  • Emulator fidelity ceiling. The local mirror is only as good as the emulator underneath. Features that the emulator can't simulate (global consistency, edge routing, real egress) still diverge.
  • Security boundary. The local mirror is developer-facing only; must never be exposed on a real public network or confused with production credentials.
  • Maintenance burden. Every new remote API endpoint implies a new local handler. Partially mitigated by schema-driven code-gen.

Seen in

Last updated · 200 distilled / 1,178 read