Node Target

Purpose and Scope

The Node target is the Flue path for running discovered agents and workflows as a standard Node.js server. It is the target to choose when you want the generated application to run on a local machine, in a container, on a VM, in CI, or on a managed Node hosting service. In the CLI workflow, Node is not a separate product surface; it is selected through the same flue init, flue dev, and flue build commands that also support Cloudflare. The important distinction is what those commands produce and how the development server behaves while your application is changing.

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

A Node-target Flue project still follows the normal Flue authoring model: agents and workflows are discovered from the selected source root, and route exposure remains an authored application concern. The CLI overview is explicit that running locally gives you the real HTTP and SDK surface while developing routes and integrations, but discovered agents and workflows are not automatically public merely because the runtime can find them. This separation matters for Node deployments because the generated server owns the runtime mechanics, while your application still decides which resources are mounted and reachable.

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

Relevant Source Files

• apps/docs/src/content/docs/cli/init.md — Defines how flue init --target node writes the initial flue.config.ts target selection without creating application resources.
• apps/docs/src/content/docs/cli/dev.md — Documents Node local development behavior, watch mode, reload draining, structured 503 admissions, and the default development port.
• apps/docs/src/content/docs/cli/build.md — Documents flue build, the Node output artifact, target selection, output directory option, and examples.
• apps/docs/src/content/docs/cli/overview.md — Places the Node target inside the everyday CLI workflow: install, develop, run one resource, build, and deploy.
• apps/docs/src/content/docs/cli/add.md — Shows how blueprints can help add Node-relevant capabilities such as database adapters, channels, sandboxes, and tooling after the base target exists.
• apps/docs/src/content/docs/cli/docs.md — Documents the offline documentation catalog that ships with @flue/cli, useful when inspecting Node target behavior from an installed CLI version.

Target Selection and Project Setup

A new Node project starts with configuration, not generated agents. flue init --target node writes a starter flue.config.ts whose target value is node. The command intentionally does not create agents, workflows, or an application entrypoint, so the generated configuration should be read as a runtime selection rather than a scaffolded application. If a supported flue.config.* file already exists, the init command refuses to overwrite it unless --force is supplied; when forced, the generated TypeScript config takes precedence while existing files remain on disk.

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

flue init --target node

import { defineConfig } from '@flue/cli/config';
 
export default defineConfig({
  target: 'node',
});

This setup step gives later CLI commands a default target, but each command can still accept target and project-location options where documented. Both flue dev and flue build accept --target <node|cloudflare>, --root <path>, --config <path>, and --env <path>. The config and environment resolution rules are part of the CLI contract: an explicitly selected env file is loaded before configuration, relative env paths resolve from the config base, and shell values win. That design lets the same source tree support local Node testing, staging configuration, and CI builds without changing application code.

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

Local Development Runtime

For day-to-day development, flue dev --target node starts a local server, watches project files, and reloads after relevant changes. The documented default port is 3583, and the command accepts --port <number> when you need to avoid a conflict or match another local integration. Node development does not write runtime artifacts to the deployment output directory; instead, it runs the project through an in-memory Vite module runtime. That distinction is useful when debugging because the dev server is a live loader, not a preview of the exact files emitted by flue build.

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

Reload behavior is deliberately more careful than simply killing and restarting the listener. On a source change, Flue pauses new agent, workflow, dispatch, and channel admissions, lets accepted work settle, then replaces the loaded application on the same port. Observation-only requests and accepted event streams do not block this drain. While a reload is draining or loading, new admissions receive a structured 503 response. If the changed source fails to load, the listener remains available in a failed state and can recover after the next valid edit.

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

There is an important boundary around that quiescence model. The CLI documentation only promises to track work that enters through Flue-managed operations. Work started outside those tracked operations, including detached promises created by application handlers, is not part of reload quiescence. In practical terms, a handler that starts background work and returns immediately should use its own lifecycle discipline. For Node development, this makes the local server predictable for normal agent, workflow, dispatch, and channel requests while avoiding a false guarantee that arbitrary detached application work will be drained during reload.

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

Build Output and Generated Server Loading

flue build is the deployment-oriented command for the Node target. It discovers agents, workflows, and an optional application entrypoint under the selected source root, then writes target-specific deployment output. For Node, the documented artifact is a runnable server module at <output>/server.mjs, with <root>/dist as the default output directory. A typical production build is therefore a short command followed by starting the generated module with Node. The target guide further describes this generated server as the component that owns HTTP handling, agent dispatch, workflow admission, and event streaming routes.

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

npx flue build --target node
node dist/server.mjs

The build command does not choose a model, add credentials, expose additional routes, or configure platform-owned bindings. The CLI overview frames it as packaging the discovered application for the selected runtime target, after which you continue into a deployment guide. For Node, that means your deployment packaging must include the generated server.mjs and the runtime dependencies expected by your application. The target documentation also notes that application dependencies are externalized rather than bundled, so a container image or hosting environment should install dependencies before starting the generated server.

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

Runtime State and Durability Considerations

The Node target is capable of durable execution, but the operational model is different from Cloudflare Durable Objects. In the Node target documentation, a project without db.ts uses process-local in-memory SQLite for canonical agent conversations, accepted submissions, and workflow-run records and indexing. That is useful for one running process and local development because accepted work can be ordered within that process. It is not durable across restarts. For any deployment where recovery matters, add a durable persistence adapter rather than treating process memory as production state.

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

When a durable adapter is present, direct prompts and dispatch(...) inputs enter the same persisted per-instance queue. Inputs for one agent instance are processed in accepted order, and a replacement process can recover canonical conversation progress and interrupted submissions. The Node target still requires one live process to own a given agent instance. A shared database supports process or host replacement, but it does not make active-active ownership or round-robin routing for the same instance safe. Multi-replica Node deployments should route each instance to one owner and avoid overlapping owners during replacement.

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

Blueprints fit this stage of adoption well. The flue add command does not install packages or write project files by itself; it fetches Markdown implementation blueprints for coding agents. Its documented blueprint kinds include database, channel, sandbox, and tooling, and the examples include database adapters and observability tooling. For a Node deployment, those blueprints are a practical way to move from a minimal generated server toward a production harness with persistence, verified ingress, local or remote sandbox behavior, and monitoring.

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

Command Reference for Node Workflows

Use these commands as the compact Node target reference. flue init --target node [--root <path>] [--force] creates the initial config. flue dev [--target node] [--root <path>] [--output <path>] [--config <path>] [--port <number>] [--env <path>] starts the local watch server, with 3583 as the default port and no Node deployment artifacts written during development. flue build [--target node] [--root <path>] [--output <path>] [--config <path>] [--env <path>] writes the deployable Node server module.

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

The broader CLI loop also includes flue run, flue add, and flue docs. The overview describes flue run as a way to execute one agent prompt or workflow invocation and exit, starting the configured runtime temporarily when an absolute server URL is not supplied. flue docs works entirely with documentation bundled inside the installed @flue/cli package, requiring no network access and matching the installed CLI version. That makes it useful in Node projects where the running CLI version is the authoritative local reference for commands and page paths.

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

Next Steps

After selecting the Node target, add the application resources that define what your server actually does: agents, workflows, routes, channels, persistence, and tooling. Start with flue dev --target node to exercise the real HTTP and SDK surface locally, use flue run for a single resource invocation, then create a production artifact with flue build --target node. If the application needs restart recovery or host replacement, prioritize a database adapter before deployment. If it needs external ingress, add a verified channel and expose it through your authored routing layer rather than assuming discovery is publication.

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