---
title: "Introducing the Cloudflare Simulator: an install without a real account"
summary: "A deliberately fake Cloudflare API, consent flow and dashboard for testing installers against controlled failures."
created: "2026-11-15"
updated: "2026-11-17"
revision: "3"
previous: "493494e1b400cc007d207ddb6040732f951e4df4"
reviewedThrough: "db9c004f146ca49dc313bc6b0a28d308d0d4b824"
sourceDigest: "736273711f9319a28dbd571c32ad2323614df34b82386fa5b9119a7800571b9e"
---

With this, your mind can exercise an installer before it asks someone to authorize a real cloud account. The simulator plays Cloudflare’s side: OAuth, account APIs, a dashboard of buttons and a simulated deployed mind. It asks for no real password, payment card or cloud credential and deploys no real Worker.

## An instance URL is its only key

`apps/cloudflare-simulator/app.ts` serves the public `fake-cf` host and its `cloudflare-simulator` alias. Creating an instance returns a long URL. Anyone holding that URL can read and change that simulated instance; it is not an authenticated private workspace. Share it only when sharing test state is intended. Put no real personal data, uploaded private configuration or credential into it.

```js
// On your own simulator host; no real cloud account is involved.
const reply = await fetch("/instances", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ scenario: "free-account" })
});
const instance = await reply.json();
```

Keep the returned URL in the test driver, not in public reports. Under it, `/state` reads the view, `/actions/<method>` accepts page actions and `/rpc` exposes the typed instance API over HTTP batch or WebSocket. A driver can set presets, answer consent and play account prerequisites without automating a real billing page. Instance creation and request counts have caps; a refusal at those limits is not a simulated provider outage.

## Separate the record from the resources

`instance.ts` defines events, scenarios, validation and the pure reducer. `backend.ts` exports the instance stream processor. The app appends events to one context per instance; the processor folds them into state read by `snapshot()`. KV marks which instances exist. Record API method, route, status and timing for diagnosis, not authorization headers or consent query strings.

The API families are split into `api-account.ts`, `api-domain.ts` and `api-workers.ts`, with shared response envelopes in `api.ts`. `store.ts` keeps simulated resources and deployment-state documents as mind files, separately beneath the instance directory. Encode every supplied path segment. Preserve stored state text when returning it; deployment tools may read it immediately after writing. Uploaded Worker code is recorded, not executed.

`hosts.ts` plays auxiliary hosts, `mind.ts` the resulting mind, and `cloud.ts` enrollment and handover. `signed.ts` implements the corresponding simulated statement checks. These are contract models, not live vendor services.

## Set the situation at consent time

`consent-form.ts` adds a form to simulated sign-in and authorization pages. It changes a made-up person, the newest account’s setup, simulated domains and failure presets. Apply changes state without answering consent; Approve applies the form then answers; Refuse changes only the consent. Validation runs before planned changes are appended. The model accepts only its reserved example-email domain and refuses domain inputs belonging to the hosting platform.

The form emits existing event types, so older instances’ processors see its changes too. Apply only edited fields: another test driver’s unrelated changes should survive. Once submitted, the page stops polling that could otherwise interrupt the authorization redirect. Test Apply followed by Refuse, invalid inputs and a consent already answered elsewhere.

OAuth models account selection, scopes, PKCE and expiration. Sign-in and installation consent are distinct. The preset for refused account creation now produces the provider-shaped refusal for a login that is too new; it does not create or age a real account.

## Fail honestly, and verify the client

An unsupported API call returns a visible Cloudflare-shaped error and records an unknown-route mark. Never proxy it to real Cloudflare as a fallback or silently return success. Presets can refuse consent, omit an account, expire access, fail deployment or delay answers. Tests cover reduction, API families, storage, played mind and Cloud behavior. A route-drift fixture detects production calls the model does not yet cover; refresh it with sanitized route shapes, never private run records.

Rebuilding needs the complete simulator folder, its processor, iterate’s SDK, Zod, the pinned UI dependencies, KV and mind-file storage. No real provider account or paid deployment is needed for the played resources, although running the hosting mind has its own costs.

The simulator remains independently callable. The current [iterate Cloud](/introducing/cloud) installer replaced its older prototype client; its present code does not implement the old alternate-provider signup flow. Do not assume an old “open installer” link proves end-to-end integration. For a new client, explicitly implement and verify an isolated alternate base for every simulated API, consent and auxiliary-host request. Keep test identities and grants separate from real ones. Simulated success verifies the modeled contract only; it cannot prove that a real provider accepts a deployment.
