Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/withastro/flue/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through installing Flue, creating a minimal agent, running the dev server, and invoking your agent via curl. By the end you’ll have a working agent and a mental model for how Flue’s build and deploy cycle works.
Flue requires Node.js ≥ 22.18. Check your version with node --version.
1

Install packages

Install the Flue runtime and CLI, plus Valibot for schema-validated results:
npm install @flue/runtime valibot
npm install -D @flue/cli
@flue/runtime is your agent’s production dependency. @flue/cli provides the flue binary for development, builds, and deployment. Valibot is used to define typed result schemas for prompt(), skill(), and task() calls.
2

Initialize the project

Run flue init to create a flue.config.ts at the project root:
npx flue init --target node
This writes the following config file:
// flue.config.ts
import { defineConfig } from '@flue/cli/config';

export default defineConfig({
  target: 'node',
});
The target field sets the default build and dev target. You can override it with --target on any CLI command. CLI flags always take precedence over the config file.
3

Set your API key

Flue routes model calls through the provider identified in the model string. For Anthropic models, set ANTHROPIC_API_KEY in a .env file:
# .env
ANTHROPIC_API_KEY=sk-ant-...
During development, pass --env .env to flue dev or flue run and Flue loads the file automatically. Later files on --env override earlier ones. Shell-set env vars always win.
4

Create your first agent

Create the directory .flue/agents/ and add a file named hello.ts:
mkdir -p .flue/agents

// .flue/agents/hello.ts
import type { FlueContext } from '@flue/runtime';
import * as v from 'valibot';

// Every agent needs at least one trigger.
// webhook: true makes this agent reachable via HTTP.
export const triggers = { webhook: true };

export default async function ({ init, log }: FlueContext) {
  // init() creates the harness: the configured handle for model,
  // sandbox, tools, and sessions.
  const harness = await init({ model: 'anthropic/claude-sonnet-4-6' });
  const session = await harness.session();

  // prompt() sends a message and waits for the agent to respond.
  // Pass `result:` with a Valibot schema to get typed, validated data back.
  const response = await session.prompt('What is 2 + 2? Return only the number.', {
    result: v.object({ answer: v.number() }),
  });

  log.info('solved arithmetic prompt', {
    answer: response.data.answer,
    tokens: response.usage.totalTokens,
    model: response.model.id,
  });

  return response.data;
}
The filename determines the agent’s name: hello.ts → agent hello. The triggers export tells Flue how to invoke this agent; webhook: true exposes it as an HTTP endpoint.
5

Start the dev server

npx flue dev --target node --env .env
Flue builds your agents and starts a watch-mode server. Edit any agent file and the server rebuilds and reloads automatically.
The dev server listens on port 3583 by default — that’s “FLUE” on a phone keypad. Override with --port.
You’ll see output like:
  ▲ Flue dev server
  → http://localhost:3583
  → watching .flue/agents/
6

Invoke your agent via HTTP

With the dev server running, invoke the hello agent in a separate terminal:
curl http://localhost:3583/agents/hello/session-1 \
  -H "Content-Type: application/json" \
  -d '{}'
The URL pattern is POST /agents/<agent-name>/<id>. The <id> segment (session-1 here) identifies the agent instance — reuse the same id to continue a conversation, or use a new id to start fresh.
7

View the streamed output

Flue streams agent events as Server-Sent Events. The final line in the response contains the run result:
data: {"type":"run_end","result":{"answer":4},"isError":false,"durationMs":1234}
Your session.prompt() call returned { answer: 4 } — the schema-validated result from the model.To continue the same conversation, POST to the same instance id again:
# Continue the same conversation
curl http://localhost:3583/agents/hello/session-1 \
  -H "Content-Type: application/json" \
  -d '{}'

# Start a fresh conversation
curl http://localhost:3583/agents/hello/session-2 \
  -H "Content-Type: application/json" \
  -d '{}'

​
Run in CI with flue run

For one-shot, scripted invocations (CI pipelines, cron jobs, local testing without a running server), use flue run. It builds the project, starts a temporary server, invokes the agent, streams output to stderr, prints the result to stdout, then shuts down: 
ANTHROPIC_API_KEY=sk-ant-... npx flue run hello \
  --target node \
  --id test-1 \
  --env .env
Pass --payload for agents that read from ctx.payload: 
npx flue run hello \
  --target node \
  --id test-1 \
  --payload '{"text": "Hello world", "language": "French"}' \
  --env .env

​
Next steps

Core concepts

Learn the full agent → harness → session → operation hierarchy.

Writing agents

Triggers, handler patterns, payload types, and the FlueContext API.

Skills and roles

Shape agent behavior with reusable Markdown instruction files.

Deploy to Node.js

Build a production artifact and deploy your agents to any Node.js host.

Build docs developers (and LLMs) love

Get started for freeTalk to us