Cloudflare Target

Purpose and Scope

The Cloudflare target is the Flue build and development mode for running agents and workflows on Cloudflare Workers. It turns discovered Flue resources into Workers-compatible output and relies on platform primitives such as Durable Objects for per-resource state, addressability, and recovery. This page is for developers who already understand the basic Flue authoring model and need to know what changes when the same application is initialized, served, built, and deployed for Cloudflare instead of Node.js.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/cli/init.md, apps/docs/src/content/docs/cli/build.md

The CLI documentation frames targets as an explicit project choice. flue init --target cloudflare writes a starter flue.config.ts whose generated target value records Cloudflare as the selected runtime, while flue dev and flue build both accept --target node|cloudflare when a command needs to override or supply that configuration. The Cloudflare target therefore is not just a deploy flag at the end of a project; it participates in configuration discovery, local development, generated output, and deployment preparation from the beginning of the workflow.

Relevant Source Files

• apps/docs/src/content/docs/cli/init.md - defines how flue init --target cloudflare creates the first target-aware flue.config.ts file and how --root and --force affect that generation.
• apps/docs/src/content/docs/cli/dev.md - documents flue dev options, default port behavior, file watching, configuration restart behavior, and the Cloudflare-specific development path through the official Workers integration.
• apps/docs/src/content/docs/cli/build.md - documents flue build, target selection, output directory selection, Cloudflare build output, and the fact that Flue prepares generated Worker and Wrangler input without rewriting authored Wrangler configuration.
• apps/docs/src/content/docs/cli/overview.md - gives the first-party CLI workflow: install @flue/cli, use flue dev, exercise resources with flue run, and create target-specific deployment output with flue build.
• apps/docs/src/content/docs/cli/add.md - documents blueprint discovery for sandboxes, channels, databases, and tooling, including the Cloudflare Shell sandbox blueprint path used by Cloudflare deployments that need durable workspace execution.
• apps/docs/src/content/docs/cli/docs.md - documents offline bundled documentation access through flue docs, which is useful when checking Cloudflare target guidance from the installed CLI version.

Cloudflare Target Model

A Cloudflare build packages Flue resources for the Workers platform rather than producing a single Node server entry. In the target documentation, generated agents and workflows run inside Durable Objects, and those Durable Objects own canonical conversation streams, immutable attachments, accepted submissions, and workflow run history. The important design consequence is that each agent or workflow instance has a platform-addressable owner for durable state. Instead of treating persistence as an external database adapter, Cloudflare uses Durable Object SQLite storage as the owning state container for generated resources.

Sources: apps/docs/src/content/docs/cli/build.md

Flue discovers agents from conventional source locations such as src/agents/ and workflows from src/workflows/, then maps each discovered resource to generated Cloudflare artifacts. The target docs describe a generated Durable Object class and a Wrangler binding for each agent and workflow. The class name is what Cloudflare tracks in Durable Object migrations, while the binding is how Worker code accesses the namespace through env. This distinction matters when reviewing generated names: migrations are deployment history, and bindings are runtime access points.

The Cloudflare target also changes the database responsibility boundary. The target docs explicitly state that Cloudflare builds do not use a source-root db.ts; a source-root database adapter file is rejected at build time for this target. That differs from Node deployments, where database adapters can provide durable persistence. On Cloudflare, the generated Durable Object is the state owner, so project authors should focus Wrangler configuration on migrations and application-owned resources instead of trying to wire Flue’s core state through a separate Node-style adapter.

Build and Development Flow

Start by installing the CLI in the project and selecting the Cloudflare target in configuration. The overview instructs users to install @flue/cli as a development dependency and invoke it through the package manager. Cloudflare development and deployment also require wrangler as a development dependency. A minimal target setup can be created with flue init --target cloudflare, optionally using --root to write into an existing application directory. That command only writes configuration; it does not scaffold agents, workflows, or an application entrypoint.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/cli/init.md

For local iteration, use flue dev --target cloudflare. The CLI reference says flue dev starts a local server, watches project files, and reloads after relevant changes. Editing or replacing an auto-discovered flue.config.* file restarts the development session with freshly resolved configuration, and invalid edited configuration leaves the command waiting for a corrected change. For the Cloudflare target specifically, development starts Vite with the official Workers integration, while Cloudflare runtime bindings continue to use the official .dev.vars, .env, and CLOUDFLARE_ENV conventions.

Sources: apps/docs/src/content/docs/cli/dev.md

For deployable output, use flue build --target cloudflare. The build command discovers agents, workflows, and an optional application entrypoint under the selected source root, then writes target-specific deployment output. The Cloudflare output path is described as a Workers-compatible application produced through the official Cloudflare Vite integration. Flue prepares generated Worker and Wrangler input files without rewriting the project’s authored Wrangler configuration, so Durable Object migration history remains in the project-root Wrangler config and passes through unchanged.

Sources: apps/docs/src/content/docs/cli/build.md

npm install --save-dev @flue/cli wrangler
npx flue init --target cloudflare
npx flue dev --target cloudflare --port 8787
npx flue build --target cloudflare

Runtime Coordinator and Platform Responsibilities

On Cloudflare, Flue’s runtime coordination is shaped by Durable Object ownership. The generated Durable Object classes provide one durable coordination point per resource instance, so accepted prompts, dispatch inputs, workflow admissions, event streams, and recovery-sensitive state can be tied to the owning object. The target docs describe generated agents and workflows as running inside Durable Objects using the Agents SDK, Workers AI, Cloudflare Sandbox, Cloudflare Shell, and other Worker primitives where appropriate. In practice, that means runtime behavior is not emulated by a long-lived local process; it is coordinated through Cloudflare’s object model.

Sources: apps/docs/src/content/docs/cli/build.md, apps/docs/src/content/docs/cli/dev.md

Wrangler remains the deployment contract between your project and Cloudflare. Flue generates its own Durable Object classes and bindings, but the project-root Wrangler configuration still owns Worker identity, compatibility settings, and migration declarations. The Cloudflare target docs emphasize that generated FLUE_* bindings should not be hand-authored in wrangler.jsonc; authors should declare migrations for generated classes and declare only application-owned bindings such as custom Durable Objects, R2 buckets, Queues, Hyperdrive configs, Browser Rendering, or Send Email bindings. The CLI build docs reinforce that Flue does not rewrite authored Wrangler configuration.

Workers AI is one of the platform model providers available to Cloudflare-targeted applications. From an authoring perspective, model selection still belongs to the agent or workflow definition and its provider configuration, while the target controls how the deployed runtime reaches Cloudflare platform services. This separation is useful when moving a project between local testing and Cloudflare deployment: the agent harness remains TypeScript-defined, but Cloudflare-only capabilities depend on Worker bindings, compatibility flags, and the deployed environment rather than Node process state.

Sandboxes, Blueprints, and Cloudflare Shell

Cloudflare deployments can use sandbox capabilities that are specific to the Workers platform. The Cloudflare Shell documentation describes an adapter that turns an application-owned @cloudflare/shell Workspace into a Flue sandbox on the Cloudflare target. Unlike a Linux shell sandbox, it provides a durable workspace and a model-facing code tool that executes JavaScript against workspace state through a Worker Loader binding. This is a good example of why the target matters: the sandbox is not just a local process helper, it depends on Cloudflare bindings and Worker execution semantics.

Sources: apps/docs/src/content/docs/cli/add.md

The CLI blueprint flow is how Flue exposes these ecosystem additions to coding agents and project authors. flue add fetches Markdown implementation blueprints; it does not install packages or write files itself. The command supports blueprint kinds for sandbox, channel, database, and tooling, and the examples include flue add sandbox @cloudflare/shell --print | opencode. For Cloudflare Shell, the blueprint guidance installs Cloudflare packages, creates a source-root sandbox adapter file, and updates Wrangler configuration with the Worker Loader binding needed by the generated adapter.

Because blueprints are instructions rather than direct mutation, review their output before applying changes. That is especially important for Cloudflare resources because Wrangler bindings, migrations, compatibility flags, and environment conventions are deployment-sensitive. Use --print when you want raw blueprint Markdown, then let a coding agent apply the implementation in your repository with full awareness of existing Worker configuration and application-owned bindings.

Compact CLI Reference

Deployment Checklist and Next Steps

Before deploying, confirm that wrangler is installed, the project target is Cloudflare, and the authored Wrangler configuration declares the required compatibility flags and Durable Object migrations for generated classes. Do not hand-author Flue’s generated runtime bindings; let the build prepare generated inputs while you maintain deployment history and application-owned resources. If a build fails because a Node-style db.ts is present, remove that persistence adapter from the Cloudflare source root and rely on Durable Object storage for Flue-managed state.

Sources: apps/docs/src/content/docs/cli/docs.md, apps/docs/src/content/docs/cli/overview.md

Use flue docs when working offline or when you need documentation that matches the installed @flue/cli package. The docs command can list the bundled page catalog, read a page as Markdown, or search for terms such as Cloudflare, Durable Object, sandbox, or deployment. After this page, read the configuration reference for target resolution, the routing guide for exposing discovered resources, the sandbox guide for execution environments, and the Cloudflare deployment guide for Wrangler-specific release steps.