Architecture
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.
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.
Transport boundary
HOSTED
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
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
INVENTORY
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
src/fleet-intent.mjs defines scopes, presence constraints, value constraints, acknowledgements, and coverage expectations. src/intent-alignment.mjs turns effective exact and forbidden intent into deterministic adapter targets only when every selected drift cell is supported.
EXECUTION
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
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
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
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
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
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.
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.
Agent interface
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, discriminated direct-change requests, structured plan digests, revision-bound pending activity, guarded undo, ordered writes, and exact verification reads.
CLI
The installed cloudflare-fleet command launches the dashboard, audits, exports or replaces intent, prepares alignment and direct-change plans, inspects activity, and performs guarded undo. A caller presents the complete plan and supplies that exact digest to apply; fresh replanning exits without mutation if it changed.
MCP
The stdio server exposes paired read, plan, and apply tools for audit, complete intent persistence, alignment, bounded direct changes, activity, and guarded undo. Every mutation displays its exact request and plan, elicits one explicit approval through authenticated short-lived request state, and enters the same fresh locked apply path. Structured results have tool-specific schemas and a serialized JSON text fallback.
Cloudflare GET requests honor Retry-After after HTTP 429 responses. An exhausted throttle aborts inventory collection instead of becoming an ordinary coverage gap, while mutation requests are never automatically retried.
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.
Mutation lifecycle
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. Bounded direct changes derive their reads and API operations from a discriminated request type rather than caller-supplied paths. 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.
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
| Document | Purpose | Hosted | Local |
|---|---|---|---|
| Fleet intent | Zone scopes, desired-state policies, acknowledgements, and expected coverage | D1 with revision checks | Ignored state file with serialized atomic updates |
| Operation activity | Reviewed plans, pending and terminal results, verification evidence, and eligible inverse plans | Transactional append and finalize operations | Independent state section under the same file lock |
| Inventory snapshot | Last complete fleet reading plus newer scoped verification patches | D1 cache record | User cache directory |
| Fleet policy | Typed operator exceptions that stay visible but do not become actionable drift | Validated Worker variable generated from an ignored file | Ignored JSON loaded into the session runtime |
Next step
The deployment guide starts hosted mode read-only and keeps local mode available.