# FlareDispatch

> BYOC CI/CD that moves the expensive half of GitHub Actions onto a Cloudflare stack you own — Workflows for orchestration, Containers for execution, Browser Rendering for e2e, R2 for cache and artifacts. Runs are typed Effect-TS programs, not YAML. The substrate is its execution environment for agentic work, consumed only through a service-binding facade.

The full text of every page is at https://flare-dispatch.fractalbox.dev/llms-full.txt.

## Overview

- [BYOC CI/CD on Cloudflare](https://flare-dispatch.fractalbox.dev/): FlareDispatch offloads the expensive half of GitHub Actions — agentic review, Playwright e2e, acceptance suites, matrix fan-outs — onto a Cloudflare stack you own.

## GitHub Actions

- [FlareDispatch GitHub Actions](https://flare-dispatch.fractalbox.dev/actions/): Reusable GitHub Actions for consuming FlareDispatch from your own repositories. Both are self-contained composite actions — no bundled runtime, no npm…
- [deploy-dispatcher-action](https://flare-dispatch.fractalbox.dev/actions/deploy-dispatcher-action/): Composite GitHub Action that deploys the FlareDispatch dispatcher Worker into your Cloudflare account using an operator overlay: you carry one file…
- [flare-dispatch-action](https://flare-dispatch.fractalbox.dev/actions/flare-dispatch-action/): Composite GitHub Action that dispatches a FlareDispatch run. It HMAC-signs a dispatch body and POSTs it to your Dispatcher Worker; the run executes…

## Run catalog

- [FlareDispatch run catalog](https://flare-dispatch.fractalbox.dev/runs/): Starter runs shipped in @fractalboxdev/flare-dispatch-runs. The Dispatcher registers them by name; Action mode dispatches via flare-dispatch-action, webhook…

## Substrate guides

- [The flare-dispatch substrate](https://flare-dispatch.fractalbox.dev/substrate/): The substrate is where agentic work runs: containers under deny-all egress, ticket-gated admission that owns the account's Containers ceiling, artifacts on…
- [BYOC upgrade runbook](https://flare-dispatch.fractalbox.dev/substrate/byoc-upgrade/): Every organization deploys its own substrate into its own Cloudflare account — no multi-tenant SaaS, no shared fleet. An org runs two workers from one…
- [Contract versioning policy](https://flare-dispatch.fractalbox.dev/substrate/contract-versioning/): packages/substrate-contract is the frozen surface consumers pin: plain structural types that survive Workers RPC structured-clone, with no dependencies and…
- [Consuming the facade](https://flare-dispatch.fractalbox.dev/substrate/facade/): The facade is the only way into the substrate (ADR-0003). A consumer holds no Durable Object binding, no container class, no D1 — one service binding,…
- [Authoring a grant profile](https://flare-dispatch.fractalbox.dev/substrate/grant-profiles/): Containers run with enableInternet = false and an empty allowlist, so nothing leaves them until a grant is issued. A grant profile is a named,…

## API reference

- [@fractalboxdev/flare-dispatch-substrate-contract](https://flare-dispatch.fractalbox.dev/reference/substrate-contract/): What a consumer's service binding exposes. Implemented by the substrate's WorkerEntrypoint classes (one named entrypoint per consumer — that binding choice,…

## Design records

- [Architecture decision records](https://flare-dispatch.fractalbox.dev/design/adr/): Decisions that settle a direction the rest of the repo then assumes. One file per decision, numbered, never edited after acceptance — a superseding decision…
- [Specs](https://flare-dispatch.fractalbox.dev/design/substrate/): plan, and success criteria. Start here.
- [ADR-0001 — Cloudflare Workflows scope: one instance per dispatch, hibernation only for bounded human decisions](https://flare-dispatch.fractalbox.dev/design/adr/0001-cloudflare-workflows-scope/): Status: proposed 2026-08-06 Related: packages/core/src/step.ts · apps/dispatcher/src/workflow.ts · runs/release-notes.ts (the one sanctioned hibernating…
- [ADR-0002 — Org context is an optional, total memory capability with MCP-speaking adapters](https://flare-dispatch.fractalbox.dev/design/adr/0002-memory-capability/): Status: proposed 2026-08-06 Related: ADR-0001 · packages/core/src/services/email.ts (the total-capability precedent) · packages/core/src/context.ts (the…
- [ADR-0003 — Context backends ingest GitHub directly; FlareDispatch does not relay](https://flare-dispatch.fractalbox.dev/design/adr/0003-no-context-relay/): Status: proposed 2026-08-06 Related: ADR-0002 — closes its final revisit trigger (a Dispatcher read endpoint for backends to pull CI-surface data)
- [ADR-0004 — Serialized run groups: one in flight, newest waiter wins, in D1](https://flare-dispatch.fractalbox.dev/design/adr/0004-serialized-run-groups/): Status: proposed 2026-09-18 Related: packages/runtime-cf/src/serial-queue-d1.ts · apps/dispatcher/src/workflow.ts · runs/worker-deploy.ts ·…
- [Slack-origin dispatches](https://flare-dispatch.fractalbox.dev/design/dispatcher/slack-origin/): A conversational Slack agent can sit in front of this dispatcher. Its ingress classifies inbound Slack events by event class — never by message content —…
- [BYOC upgrade runbook — moving the dispatcher onto the substrate](https://flare-dispatch.fractalbox.dev/design/substrate/adoption-runbook/): The stage-2 exit in platform.md § Adoption plan, written as the sequence an operator runs. Two switches drive it and they are deliberately separate:
- [Architecture Decision Records](https://flare-dispatch.fractalbox.dev/design/substrate/adr/): Status is about the decision. Implementation is about the code. They shared one word until now, and one word could not carry both — which is how this…
- [Credential boundary — migration status](https://flare-dispatch.fractalbox.dev/design/substrate/credential-boundary/): ADR-0006 states the rule: no long-lived credential is reachable from inside a container — env, argv, or filesystem. The rule takes effect per credential…
- [The flare-dispatch substrate — execution environment for agentic work](https://flare-dispatch.fractalbox.dev/design/substrate/platform/): The substrate is where FractalBox's agentic work runs: containers under a deny-all egress policy, admission that owns the account's Containers ceiling,…
- [ADR-0001: The execution substrate is its own component](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0001-substrate-as-its-own-component/): fractalbot and flare-dispatch were building the same execution environment twice: sandbox admission, CF Workflows quirks (instance-id sanitization, step…
- [ADR-0002: The substrate lives inside the flare-dispatch monorepo, with no name of its own](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0002-substrate-inside-the-flare-dispatch-monorepo/): The substrate needs a home and an identity. The candidates: a hard module inside this repo (the founding spec's reviewed recommendation), a standalone repo…
- [ADR-0003: Consumers reach the substrate only through a service-binding facade](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0003-facade-only-consumption/): A cross-script Durable Object namespace binding would hand consumers the full Sandbox class surface — including the SDK's inherited, unfenced exec — and…
- [ADR-0004: Admission is enforced by ticket, and the substrate alone owns the ceiling](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0004-admission-enforced-by-ticket/): Both consumers draw on one account-level Containers ceiling with no view of each other. flare-dispatch built a strongly-consistent D1 FIFO counting…
- [ADR-0005: Deny-all egress with named grant profiles](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0005-deny-all-egress-with-grant-profiles/): fractalbot's egress engine (its ADR-0005; src/egress.ts, src/exec.ts) is the reviewed implementation: deny-all class state arming interception,…
- [ADR-0006: No long-lived credential reachable from inside a container](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0006-credential-boundary/): flare-dispatch injects secret values into the command env with best-effort substring redaction (6 of ~19 catalog runs take a secrets input; wrangler deploy…
- [ADR-0007: Irreversible commands require an approval attestation at the exec surface](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0007-approval-attestation-at-exec/): fractalbot's ALWAYSAPPROVE regex floor (git push, wrangler deploy|secret|d1, terraform apply, publishes) is enforced in exactly one path — its TaskWorkflow…
- [ADR-0008: The substrate is verdict-neutral — execution facts only](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0008-verdict-neutral-execution-facts/): flare-dispatch's runs end in a terminal CI verdict feeding check-runs; fractalbot's tasks move through conversational states (active / awaitinghuman / done)…
- [ADR-0009: Two-tier budgets — the substrate meters executions and caps consumers](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0009-two-tier-budgets/): Both consumers built spend fences at different granularity: fractalbot's BudgetLedger is conversation-scoped and provider-window-aware (per-task dollar cap,…
- [ADR-0010: Named image classes, selected by policy — never by the model or the payload](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0010-named-image-classes-policy-selected/): Cloudflare requires a distinct Durable Object class per container image; every image must exist at deploy time as a class in the containers config — there…
- [ADR-0011: The sandbox SDK pin is a security surface](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0011-sdk-pin-as-security-surface/): The deny-all posture depends on verified internals of pre-1.0 SDKs: allowedHosts = [] engages interception only because of how @cloudflare/containers tests…
- [ADR-0012: A process that outlives the exec fence holds no grant](https://flare-dispatch.fractalbox.dev/design/substrate/adr/0012-processes-that-outlive-the-exec-fence/): ADR-0005's fence closes the grant window when the exec returns: apply, run, kill, then revoke. The kill is what makes the revoke meaningful — a backgrounded…