MIT Licensed

irk-sandbox

Local Cloudflare API mock server backed by real Miniflare 4 instances. Test Workers, D1, KV, R2, and dispatch namespaces without touching production.

Explore Features Quick Start

388+

API Endpoints

610+

Tests

CF Services

Docker Required

Three-Listener Architecture

A single Node.js process runs three parallel listeners to simulate the full Cloudflare infrastructure.

HTTP

API Server

:8787

Full Cloudflare REST API mock. D1, KV, R2, Workers, Queues, Workflows, Durable Objects, Secrets, DNS, Zones.

api.cloudflare.com/client/v4

TLS

Worker Router

:8443

SNI-based subdomain routing. Each worker gets its own HTTPS endpoint, simulating *.workers.dev.

<worker>.<account>.localhost:8443

Dashboard

:8788

Svelte 5 SPA for inspection and observability. Storage browsers, script viewer, tail logs, coverage reports.

localhost:8788/ui/

Cloudflare Services Covered

Full API fidelity for 12 Cloudflare services. Every response matches real API shapes — same envelope, same error codes, same field names.

D1

Full

Create databases, execute SQL with parameters, list databases, migrations

KV

Full

Namespace CRUD, key get/put/delete/list with prefix and pagination

R2

Full

Bucket CRUD, object upload/download/delete/list, multipart read

Durable Objects

Full

Class registration, SQLite storage, alarms, WebSocket Hibernation

Queues

Full

Producer/consumer wiring, queue CRUD, consumer assignment

Workflows

Full

WorkflowEntrypoint, step.do/sleep/waitForEvent, cross-script bindings

Dispatch Namespaces

Full

Workers for Platforms — script upload, invoke with binding pass-through

Workers

Full

Multipart upload (wrangler-compatible), service bindings, tail consumers

Static Assets

Full

2-phase upload, _routes.json routing, run_worker_first support

Analytics Engine

Full

Dataset CRUD, data ingestion, query support

Secrets

Full

PUT/DELETE/GET matching CF security model (names-only retrieval)

DNS & Zones

Full

Zone CRUD, DNS records management, Hyperdrive configs

API Fidelity

Not a mock — a faithful simulation. Every response matches real Cloudflare API shapes, enforced by type-level guarantees and shape-drift testing.

Stored*/toCf*Shape pattern

Pure projection functions make response fabrication a type error

Ajv shape-drift testing

Hard gate + property-coverage ratchet across 8+ resource families

OpenAPI codegen

388 stubs auto-generated from Cloudflare's public schema — git diff reveals drift

CR-FID-001

No crypto.randomUUID(), Date.now(), or bare now() in response builders

Response envelope

{
  "success": true,
  "result": {
    "id": "d1-abc123",
    "name": "customers",
    "version": "production",
    "num_tables": 5,
    "file_size": 2048000,
    "created_at": "2026-05-20T..."
  },
  "errors": [],
  "messages": []
}

Built-in Dashboard

Svelte 5 SPA with live storage browsers, script inspection, log streaming, and API coverage reports.

Storage Browsers

D1 SQL query browser, KV key browser, R2 object browser, Assets file browser with syntax highlighting.

Worker Inspector

Script source viewer, binding inspector, tail log streaming. See exactly what's running.

Observability

SSE log stream, CF-Ray tracing, request/response capture, 5-min/1h metric aggregation, p50/p95 latency.

Coverage Reports

Implemented/stubbed/missing endpoint counts, live hit frequency, Istanbul worker code coverage with merged LCOV.

Quick Start

Terminal

# Launch the sandbox
$ irk-sandbox --port 8787 --worker-port 8443

# With HTTPS (auto-generates certs)
$ irk-sandbox --tls

# Point wrangler at the sandbox
$ export CLOUDFLARE_API_BASE_URL=http://127.0.0.1:8787
$ export CLOUDFLARE_API_TOKEN=any-token
$ wrangler deploy

programmatic.ts

import { startSandbox } from "irk-sandbox";

await startSandbox({
  port: 8787,
  workerPort: 8443,
  accountIds: ["acme", "globex"],
  tls: { autoGenerate: true },
  coverage: {
    enabled: true,
    output: "./coverage/integration.lcov",
  },
});

Design Decisions

Every architectural choice has a rationale.

Hono over Express

Web Standards API matches CF Workers runtime. Zero impedance mismatch for Workers developers.

Miniflare 4 backend

Programmatic API runs real D1/KV/R2 — not mocks. No Docker dependency required.

HTTP-only external API

No TypeScript SDK — wrangler, IrK, and curl all speak HTTP. Lowest coupling, universal integration.

Context-interface pattern

Lightweight context bags avoid god-object anti-pattern. Engine decomposed to ~727 LOC coordination layer.

Per-account TLS via SNI

Single wildcard can't match 2-level subdomains. Browser-trusted certs with production-like routing.

CfError class + middleware

Single serialization boundary. 62 throw sites, consistent envelope handling. Route handlers become narrative code.

HipsterShop Reference

A 7-worker e-commerce application demonstrating the full Workers for Platforms architecture. Account-level workers, dispatch namespaces, D1, Durable Objects, KV, Queues, and static assets.

shop-ui (account + static assets)

shop-gateway (account router)

shop-catalog D1 + R2

shop-cart Durable Objects

shop-inventory KV

shop-checkout D1 + Queues

shop-fulfillment Queues + KV + D1

Built With

Hono

Web Standards server

Miniflare 4

Real CF runtime

Svelte 5

Dashboard SPA

TypeScript 6

Strict ESM

Vitest

610+ tests

Biome

Lint + Format

Vite 8

Build tool

Node 24

LTS runtime

See the Platform

irk-sandbox powers the development of IrK — the multi-tenant orchestration platform that deploys enterprise systems on Cloudflare in hours.

Explore IrK Platform