Quickstart

Purpose and Scope

This quickstart gives you the shortest supported path from an empty directory to a running Flue agent. Flue is a TypeScript framework for building AI agents with a harness-driven architecture: instead of only calling an LLM API, you define the context, runtime, model, instructions, and execution target that let an agent do useful autonomous work. The quickstart intentionally starts with a coding-agent-assisted setup path, then provides the manual commands for readers who want to see or control every file created along the way.

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

Use this page when you are creating your first project, validating that your local environment can run Flue, or deciding whether to initialize for Node.js or Cloudflare. It does not try to cover every agent capability. After the first run succeeds, you should move to the dedicated guides for building agents, workflows, configuration, sandboxes, and deployment so that your initial example can become a real application surface rather than a one-command demo.

Relevant Source Files

apps/docs/src/content/docs/getting-started/quickstart.mdx — The canonical first-party quickstart content. It defines the prerequisites, automatic installation prompt, manual install commands, first agent module, local run command, and recommended next steps.

Prerequisites

Before installing Flue, confirm that your environment has Node.js >=22.19.0. The quickstart also assumes you have at least one model specifier, such as anthropic/claude-sonnet-4-6 or cloudflare/@cf/moonshotai/kimi-k2.6, and credentials for the corresponding provider when credentials are required. Cloudflare model specifiers under cloudflare/* are called out as built-in model access, while the Anthropic example uses an ANTHROPIC_API_KEY environment variable stored in .env.

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

A coding agent such as Claude Code or Codex is recommended because the Flue docs position several setup and authoring tasks around local coding-agent assistance. A container sandbox is optional for the first run: Flue includes a built-in virtual sandbox that is suitable for many workloads, and the docs point readers toward container sandboxes only when they need a real VM-style environment. For a first project, focus on getting Node, a model, and credentials working before expanding the execution environment.

Automatic Installation

The recommended path is to delegate the setup to your coding agent. Copy the prompt from the docs and paste it into your coding agent: Read https://flueframework.com/start.md then help create my first agent.... That instruction tells the agent to read Flue’s start material, guide the setup in a new or existing project, and answer project-specific questions. This path is useful because Flue applications are not just package installs; they involve a target, configuration, source files, and runtime conventions that a coding agent can apply to the project you already have.

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

Automatic installation is the best first choice when you want Flue’s conventions applied correctly without memorizing every file. The resulting project should still be understandable: the manual section below shows the same essential steps, including installing the runtime and CLI, creating flue.config.ts with flue init, writing an agent module, and invoking that discovered agent. If the coding agent changes filenames or targets, compare its output against these primitives so you know what Flue will discover and run.

Core Primitives

A Flue quickstart project has a few core primitives. The runtime package, @flue/runtime, provides public authoring APIs such as defineAgent. The CLI package, @flue/cli, provides commands such as flue init and flue run. A target selects where the generated application runs; the quickstart supports node and cloudflare. A model specifier names the LLM provider and model. An agent module is a TypeScript file whose default export registers an addressable agent.

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

The first agent is deliberately minimal so you can see what each field means. The model field selects the LLM, and instructions provide the durable behavioral prompt for this agent. Later guides add tools for calling application capabilities, skills for reusable knowledge, workflows for bounded operations, sandboxes for isolated execution, and channels for verified ingress from external systems. The quickstart’s success condition is narrower: prove that Flue can discover a named agent and run one prompt through the configured runtime.

Manual Installation Flow

Create a new directory, install the runtime, install the CLI as a development dependency, write your provider key to .env, and initialize a target. The flue init command creates flue.config.ts; this is the configuration file that ties the project to the selected runtime target. The quickstart uses Anthropic credentials as the example, but it explicitly notes that you can use any model provider supported by Pi and should consult Pi’s provider documentation for supported API key behavior.

npm install @flue/runtime
npm install --save-dev @flue/cli
echo 'ANTHROPIC_API_KEY="your-api-key"' > .env
npx flue init --target node # or: --target cloudflare

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

After writing .env, add it to .gitignore and do not commit provider credentials. That warning matters even in a quickstart because the example demonstrates real provider authentication, not a mocked model. Choosing --target node gives you the local Node.js path described by the quickstart command, while --target cloudflare prepares the project for the Cloudflare runtime path. Either way, the next step is the same: create an agent module that Flue can discover by filename.

Create and Run the First Agent

Create agents/hello-world.ts and default-export a defineAgent call. The filename is part of the public discovery convention: the quickstart states that agents/hello-world.ts becomes available in Flue as hello-world. The module below uses Claude Sonnet and a single instruction string, which keeps the first run focused on discovery, model configuration, and invocation rather than on tools, sandbox behavior, or multi-step workflows.

import { defineAgent } from '@flue/runtime';
 
export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  instructions: 'Tell a funny "hello world" engineering joke.',
}));

Run the discovered agent with flue run, passing a JSON input payload. The command starts the configured Node.js or Cloudflare runtime, invokes the agent through the application, prints the response, and exits. This means the quickstart is testing the same application path Flue will use later, not only importing the module directly. If this command succeeds, you have verified package installation, configuration, discovery, provider credentials, model access, and the basic agent execution loop.

npx flue run hello-world --input '{"message":"Tell me a joke."}'

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

Next Steps

Once the first response prints, expand the project in the direction of your use case. If you selected the Cloudflare target, continue to the Cloudflare deployment material so the generated Worker can be configured and run. If you want longer-lived behavior, read the Agents concept material to understand continuing interactions. If you need bounded operations with explicit inputs and outputs, move to Workflows. For runtime details, review Configuration and Sandboxes so target settings, local environment behavior, and execution capabilities are explicit before you add real tools or external ingress.

Sources: apps/docs/src/content/docs/getting-started/quickstart.mdx

Ask a question...