Architecture

Shared fleet logic behind narrow operator interfaces

Fleet keeps comparison and desired-state logic in shared services while browser, CLI, and local MCP interfaces protect credentials, persistence, and Cloudflare API access according to their trust boundaries.

Deployment architecture

Hosted and local sessions load the same asset graph and expose the same inventory, intent, activity, and Cloudflare transport contracts. Operator-specific state is deliberately outside the published tree.

Cloudflare Fleet architecture showing hosted and local transports, D1, private files, and constrained Cloudflare API access.

Transport boundary

Two paths, equivalent application contracts

HOSTED

Access and Worker

Cloudflare Access authenticates the user at the edge. The Worker independently validates the signed assertion against the configured application audience and team-domain issuer before serving assets or API responses. D1 provides transactional persistence. The Cloudflare API token exists only as an encrypted Worker secret.

LOCAL

Launcher and loopback broker

The launcher creates a private temporary runtime and starts a broker on a random loopback port. The browser receives a random session capability, never the account token. The broker persists validated snapshots and state through mode-restricted local files and removes runtime material after the last dashboard connection closes.

Component map

Responsibilities stay explicit

INVENTORY

Read and normalize

src/inventory.mjs performs complete and scoped reads. src/matrix.mjs and src/facet-equivalence.mjs turn endpoint-specific data into stable identities, comparison values, and capabilities.

INTENT

Describe expected state

src/fleet-intent.mjs defines scopes, presence constraints, value constraints, acknowledgements, and coverage expectations. src/zone-alias-intent.mjs adds a reusable strict canonical passthrough value and exact resource envelope. src/rate-limit-intent.mjs combines the Free rate-rule slot and its hostname-complement WAF skip, while src/rate-limit-remediation.mjs owns fail-safe cross-phase transitions. src/intent-alignment.mjs turns effective exact and forbidden intent into deterministic adapter targets only when every selected drift cell is supported.

EXECUTION

Plan and verify

src/alignment-service.mjs, src/fleet-change.mjs, and src/intent-plan.mjs bind bounded requests to deterministic digests. src/write-executor.mjs journals Cloudflare changes, executes them in order, and delegates exact authoritative rereads to src/write-verification.mjs.

HOSTED BACKEND

Constrain and persist

src/hosted/worker.mjs owns routing, src/hosted/access.mjs validates Access, src/hosted/proxy-policy.mjs allowlists requests, and src/hosted/d1-store.mjs supplies transactional state.

LOCAL BACKEND

Isolate each session

cloudflare-fleet dashboard delegates to the compatible launch.sh session launcher, src/session-broker.mjs serves and proxies it, and the state, intent, activity, and cache stores validate every persisted document.

AUDIT

Report without mutation

src/audit.mjs produces Markdown, JSON, or self-contained HTML. Core checks use the same inventory and intent model; deep mode adds bounded DNS, endpoint, account-resource, and dependency evidence.

AGENT INTERFACE

Expose bounded operations

src/fleet-service.mjs supplies the complete headless local contract used by src/cli.mjs and src/mcp.mjs. It covers audit inputs, intent persistence, alignment, bounded direct changes, activity, guarded undo, and verified recovery without an arbitrary API passthrough.

Desired-state convergence

Alignment is an explicit, all-or-nothing plan

An operator can start from one drifting cell, an entire matrix row, or one saved policy's effective scope. Fleet composes layered exact expectations, preserves fields outside authored subsets, materializes zone-relative values, and maps forbidden presence to reversible removals where an adapter exists.

Intent alignment architecture showing cell, row, and policy scopes combining observed state, layered intent, and endpoint adapters before branching to a blocked safe stop, an already-aligned stop, or a full-account facet read and reviewed write flow.
Fresh scope, complete decision

The live preflight reads the relevant facet across every zone in the account, verifies that fleet membership is unchanged, reevaluates the latest saved intent, and refuses the entire row or policy action if any selected drift cell lacks a deterministic adapter. A cell action deliberately narrows only the action scope, not the account-wide membership and read check. Blocked controls render the exact reason in both the matrix and intent manager.

Alias-only zones fail closed

Canonical passthrough intent inspects serving DNS, every editable ruleset phase, Worker routes and custom domains, Pages domains, SSL for SaaS custom hostnames, load balancers, health checks, waiting rooms, Web3 hostnames, and snippets. Each extra resource carries its canonical owner in audit evidence. Missing coverage or an attachment without a reversible adapter blocks the complete alignment.

Rate-limit host scope is cross-phase state

The Free rule expression cannot select a hostname, so the exact value includes both the http_ratelimit rule and every http_request_firewall_custom skip targeting that phase. Fresh alignment reads both phases. Creation and restoration place the skip first; scope changes disable the rate rule around the skip edit; removal deletes the rate rule first. Reversing a verified transition retains the same safety order.

Agent interface

Automation uses the same bounded state machine

The CLI and local stdio MCP server call the shared fleet service instead of duplicating dashboard planning. Both expose complete revisioned intent, policy, row, and cell alignment selectors, single and batched discriminated direct-change requests, structured plan digests, revision-bound pending activity, guarded undo, ordered writes, and exact verification reads.

CLI

Explicit noninteractive approval

The installed cloudflare-fleet command launches the dashboard, audits, describes reusable alias and rate-limit values, exports or replaces intent, prepares alignment and direct-change plans, inspects activity, and performs guarded undo. Direct-change input may contain one request or one bounded batch envelope. A caller presents the complete plan and supplies that exact digest to apply; fresh replanning exits without mutation if it changed.

MCP

Interactive protocol confirmation

The stdio server exposes typed alias and hostname-scoped rate-limit descriptions plus paired read, plan, and apply tools for audit, complete intent persistence, alignment, bounded direct changes, activity, and guarded undo. Every apply displays its exact request and plan through authenticated short-lived request state before entering the same fresh locked apply path. Single-change tools retain per-review-field decisions. Explicit alignment and direct-change batches show every operation across bounded, ordered fields in one form, requiring each review acknowledgement before a separate final whole-batch approval. Authenticated request state binds the field count and approval mode; only a complete valid response can enter the fresh apply path. Worker incident capture and verification save explicitly requested fresh evidence without a Cloudflare mutation. Structured results have tool-specific schemas and a serialized JSON text fallback.

Retrieval shares comparison and intent semantics

Local and hosted CLI/MCP reads use one retrieval service. Activity summaries are filtered and paginated in D1 before transfer; standalone files are projected after loading. Exact resource discovery reads one zone and family, with detail endpoints for known IDs. Facet inspection reads the selected category across account zones so policy precedence and uniqueness retain their full context, then projects only the requested facet and zone. Observed values, policy composition, acknowledgement validity, and capability labels reuse the dashboard modules.

Pages bind their query and account to a stored revision or observed-content digest. Responses declare freshness, requested scope, incomplete coverage, and value truncation. They are live reads rather than retained snapshots; a changed revision requires restarting pagination. Collection pagination follows provider metadata and fails closed when it stalls or exceeds its bounds. Discovery cannot supply a cached substitute for the fresh planning and verification required by writes.

Throttle-aware reads

Cloudflare GET requests honor Retry-After after HTTP 429 responses. Both dashboard proxies preserve the upstream delay. Concurrent reads through the same API client recheck the shared cooldown before dispatch, so another response can extend a wait; cancellation stops waiting reads before another request. CLI and MCP reads use the same bounded retry behavior. An exhausted throttle aborts inventory collection instead of becoming an ordinary coverage gap, while mutation requests are never automatically retried.

No raw control-plane tool

Neither interface accepts arbitrary Cloudflare methods or paths. Complete fleet intent replacement is a separate local persistence operation with account, schema, revision, diff, digest, and lock checks; it cannot smuggle a Cloudflare request. The direct local process holds the configured token, so its host environment and outputs remain part of the trusted operator boundary.

Scoped Worker diagnostics

src/worker-service.mjs is shared by the dashboard's bounded backend commands, CLI, and MCP. Configuration reads are independent of log availability. Invocation-only evidence pages group event type, outcome, and version while retaining separate HTTP status counts. Projections expose binding names/types, resource links, and known fixed error signatures without source bundles or request payloads.

Inspection requires an explicit worker or supported findingId. Per-version handlerEvidence distinguishes explicit script handlers, an empty set inferred from the recognized assets-only metadata shape, and unknown coverage. Static-assets routing or null handlers alone cannot establish the absence of script handlers. Missing handler evidence does not discard independently projected bindings, and fixed diagnostic reasons distinguish metadata gaps from denied or failed reads without exposing arbitrary upstream errors. All serving versions must support a retained scheduled handler.

Schedule plans bind exact account and Worker identity, observed schedule sets, serving deployment, and saved intent revision. The shared executor persists the journal before the schedule-only write and verifies configuration before deriving an inverse. A separate fresh-evidence assessment accounts for Cron propagation, sampling, and retained schedule coverage. Incident supersession preserves previous assessments instead of erasing them.

Synthetic Worker inspection separating scheduled exceptions from successful serving-version HTTP requests and an old-version 503.
One resource, independent configuration coverage, and bounded invocation evidence.

Mutation lifecycle

A write is a verified state transition, not a button click

The plan is rebuilt from fresh reads scoped to the affected resource surface. Intent alignment widens that surface across the complete account so newly divergent zones cannot be skipped. Alias cleanup edits or creates one canonical redirect and removes only extra DNS records or rules with lossless inverse adapters; serving DNS and the selected canonical redirect are protected from collateral deletion. Rate-limit alignment orders its WAF skip and rate-rule operations so a partial transition cannot activate the rule outside its selected hosts. Bounded direct changes derive their reads and API operations from a discriminated request type rather than caller-supplied paths. A direct-change batch composes those reads, refuses blocked members and overlapping target paths, and binds the remaining ordered operations to one digest. A pending activity record is durable before the first mutation. Verification patches the visible matrix and cache only after the backend rereads the exact affected resources. Guarded undo rereads the recorded post-write targets before review and again before sending the inverse.

Reviewed write flow from desired state through live read, plan, confirmation, pending journal, execution, verification, cache patch, and guarded undo.
No silent widening

If a planner cannot identify an exact writable endpoint, required dependency, or authoritative verification read, that path remains comparison-only. Fleet does not fall back to a generic write.

State model

Durable documents have separate jobs

DocumentPurposeHostedLocal
Fleet intentZone scopes, desired-state policies, acknowledgements, and expected coverageD1 with revision checksIgnored state file with serialized atomic updates
Operation activityReviewed plans, pending and terminal results, verification evidence, and eligible inverse plansTransactional append and finalize operationsIndependent state section under the same file lock
Worker recordsExplicit schedule intent, owning configuration review, and append-only incident assessments with supersessionAccount-scoped revision checks and a bounded execution leaseOptional workers section with serialized atomic updates
Inventory snapshotLast complete fleet reading plus newer scoped verification patchesD1 cache recordUser cache directory
Fleet policyTyped operator exceptions that stay visible but do not become actionable driftValidated Worker variable generated from an ignored fileIgnored JSON loaded into the session runtime

Next step

Choose the hosted or local path.

The deployment guide starts hosted mode read-only and keeps local mode available.

Open deployment