Getting Started

Flue is the open agent framework, from the creators of Astro. Use a React-like hooks API to build agents in TypeScript using your favorite LLMs. Run them locally or deploy them anywhere: Node.js, Cloudflare, GitHub Actions, GitHub CI/CD, etc.

Prerequisites

• Node.js — >=22.19.0 minimum required version.
• LLM — API key(s) to connect to your favorite model provider. Flue is built on Pi, and supports all Pi providers out of the box. Flue’s Cloudflare runtime provides a built-in cloudflare/* AI gateway, no API keys required.

Automatic Installation

Copy this prompt and paste it into your coding agent. Your agent will guide you through setting up an agent in a new or existing project, and help answer any questions you might have along the way.

Your coding agent will run flue init to automatically initialize a new Flue project in the directory of your choice. You can run this command yourself as well, if you prefer.

Manual Installation

The AI-guided prompt above is strongly recommended for most users. Follow the steps below if you prefer to set things up yourself.

In a new directory, install the runtime and the CLI:

npm install @flue/runtime @flue/cli

Then, create a basic flue.config.ts file:

import { defineConfig } from '@flue/runtime/config';

export default defineConfig({
	target: 'node', // or 'cloudflare'
});

And finally, create your first src/agents/assistant.ts:

// The `'use agent'` directive marks the Assistant() function below as a Flue agent.
'use agent';
import { useModel } from '@flue/runtime';

// This is your first agent: `Assistant`.
// It's return value is your agent's instructions, which become the agent's "system" instructions.
// Flue Hooks like `useModel()` allow you to customize and modify your agent abilities.
export function Assistant() {
	useModel('anthropic/claude-haiku-4-5');
	return 'You are a helpful assistant. Keep replies short.';
}

Congratulations, you just built your first agent! From here you can shape its behavior and add capabilities — or keep going and put it behind a real server.

You can use any Model/Provider that Pi supports. In the example above, we use Claude Haiku. Whichever you choose, just be sure to provide the required API keys to the agent runtime. Its recommended to use a .env file to manage your API keys:

# .env
ANTHROPIC_API_KEY="your-api-key"

Run your agent locally

You can now spin up new agents from your terminal, running on your local machine:

npx flue run src/agents/assistant.ts --message "Say hello in five words or fewer."

Agents are addressable, so you can message with a specific agent by passing an agent ID (--id). Agent conversations are persistent — the second message remembers the first. See flue run for the full set of flags.

npx flue run src/agents/assistant.ts --id hello-1 --message "What's a good name for a pet crab?"
npx flue run src/agents/assistant.ts --id hello-1 --message "Give me three more."

Congratulations! You just ran your first Flue agent. You can use flue run to run agents on your local machine, or in CI environments like GitHub Actions and GitLab CI/CD.

Deploy your agent

To host your agent remotely, you’ll need to deploy it. Flue uses Hono and Vite to power its server framework and build pipeline, respectively. Follow the following steps to build your agent for deployment.

1. Install dependencies

npm install @flue/vite hono vite

2. Configure the project

Create two small config files at the project root:

import { flue } from '@flue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [flue()],
});

If you are deploying to Cloudflare, then you should also install @cloudflare/vite-plugin and add cloudflare() after flue() in the Vite plugins array. see the Cloudflare runtime guide for more.

3. Build your app router

src/app.ts is the special file where your Flue app router always lives. Create your Hono application instance, mount your agent, and export it so that it gets picked up by your build.

import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { Assistant } from './agents/assistant.ts';

// 1. Create your Hono application instance.
const app = new Hono();
// 2. Define your agent routes.
app.route('/agents/assistant', createAgentRouter(Assistant));
// 3. Export your application.
export default app;

The createAgentRouter() helper will define and mount your agent routes: POST /:id, GET /:id, POST /:id/abort, etc. See Routing for a full walkthrough of how routing works in Flue.

4. Start the dev server

As mentioned, Flue leverages Vite to power its dev and build pipeline. To spin up your dev server, run vite dev:

npx vite dev

Vite spins up your app.ts (by default at http://localhost:5173) application and servers your agents at the routes that you defined. Test your setup by sending your agent a message — one POST per message, 202 on admission:

curl -X POST http://localhost:5173/agents/assistant/hello-1 \
  -H 'content-type: application/json' \
  -d '{"kind":"user","body":"Tell me a joke."}'

The hello-1 in the URL is the agent ID, the same --id you passed to flue run above. Read the conversation back with curl "http://localhost:5173/agents/assistant/hello-1?view=history", or use the SDK and React hooks when you’re ready to build real product experiences.

vite build will produce a runnable dist/server.mjs build output for the "node" runtime target, or a deployable Cloudflare Worker when configured with the "cloudflare" runtime target.

Congratulations, you’ve completed our quickstart guide! You have created your first Flue agent, run it locally, and successfully built it for production.

Next steps

• Agents — configure the model, add capabilities, and understand how conversations persist over time.
• Tools, Skills, and Sandboxes — give your agent real capabilities and a workspace to work in.
• Routing — mount additional agents and application routes in app.ts.
• Deploy to Cloudflare or Node.js — host your agent for real traffic.
• SDK and React — build product experiences on top of a deployed agent.