Flue (withastro/flue) — README + homepage

Experimental — Flue is under active development. APIs may change. Looking for v0.0.x? See the v0.0.x branch.

Repo metadata (GitHub API)

• Owner: withastro (the Astro framework org)
• Created 2026-02-07; last push 2026-05-03
• 1,800 stars, 91 forks, 8 open issues
• License: Apache-2.0
• Primary language: TypeScript
• Default branch: main; legacy v0.0.x lives on its own branch
• Description: "The sandbox agent framework."
• Homepage: https://flueframework.com

Tagline (homepage)

Not another SDK. Build powerful, autonomous agents with Flue's programmable TypeScript harness.

Stop renting someone else's agent. Off-the-shelf AI tools are built for a general audience and struggle to fit to your product, your data, your customers, or your exact workflows.

Built on the architecture that makes coding agents like Claude Code and Codex so powerful — agents capable of planning, gathering context, writing files, spawning subagents, and problem-solving.

Write once, deploy anywhere — Node.js, Cloudflare Workers, GitHub Actions, GitLab CI/CD, and several others.

Replaces: Dosu, Greptile, CodeRabbit (listed as alternatives users might otherwise consider).

README — Flue

Flue is The Agent Harness Framework. If you know how to use Claude Code (or OpenCode, Codex, Gemini, etc)... then you already know the basics of how to build agents with Flue.

Flue is a TypeScript framework for building the next generation of agents, designed around a built-in agent harness. It's like Claude Code, but 100% headless and programmable. There's no baked-in assumption like requiring a human operator to function. No TUI. No GUI. Just TypeScript.

But using Flue feels like using Claude Code. The agents you build act autonomously to solve problems and complete tasks. They require very little code to run — most of the "logic" lives in Markdown: skills, context, and AGENTS.md.

Flue isn't another AI SDK. It's a proper runtime-agnostic framework — think Astro or Next.js, but for agents. Write once, build, and deploy your agents anywhere (Node.js, Cloudflare, GitHub Actions, GitLab CI/CD, etc).

Packages

Examples

Quickstart — virtual sandbox + typed result schema

The simplest agent — no container, no tools, just a prompt and a typed result.

Unless you opt-in to initializing a full container sandbox, Flue will default to a virtual sandbox for every agent, powered by just-bash. A virtual sandbox is going to be dramatically faster, cheaper, and more scalable than running a full container for every agent, which makes it perfect for building high-traffic/high-scale agents.

// .flue/agents/hello-world.ts
import type { FlueContext } from '@flue/sdk/client';
import * as v from 'valibot';

export const triggers = { webhook: true };

export default async function ({ init, payload }: FlueContext) {
  const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });
  const session = await agent.session();
  const result = await session.prompt(`Translate this to ${payload.language}: "${payload.text}"`, {
    result: v.object({
      translation: v.string(),
      confidence: v.picklist(['low', 'medium', 'high']),
    }),
  });
  return result;
}

Support agent — virtual sandbox + R2-backed knowledge base

import { getVirtualSandbox } from '@flue/sdk/cloudflare';
// ...
const sandbox = await getVirtualSandbox(env.KNOWLEDGE_BASE);
const agent = await init({ sandbox, model: 'openrouter/moonshotai/kimi-k2.6' });

Mount the R2 knowledge base bucket as the agent's filesystem. The agent can grep, glob, and read articles with bash, but without needing to spin up an entire container sandbox.

Because this agent is deployed to Cloudflare, message history and session state are automatically persisted for you. So you (or your customer) can revisit this support session days, weeks, or years later and pick up exactly where you left off.

Issue triage — sandbox: 'local' + scoped privileged commands

const npm = defineCommand('npm');
const gh  = defineCommand('gh', { env: { GH_TOKEN: process.env.GH_TOKEN } });

const agent = await init({ sandbox: 'local', model: 'anthropic/claude-opus-4-7' });
const session = await agent.session();
const result = await session.skill('triage', {
  args: { issueNumber: payload.issueNumber },
  commands: [gh, npm],
  result: v.object({
    severity: v.picklist(['low','medium','high','critical']),
    reproducible: v.boolean(),
    summary: v.string(),
    fix_applied: v.boolean(),
  }),
});

'local' mounts the host filesystem at /workspace — ideal for CI where the repo is already checked out. Skills and AGENTS.md are discovered automatically from the workspace directory.

Coding agent — Daytona container sandbox

import { Daytona } from '@daytona/sdk';
import { daytona } from '@flue/connectors/daytona';

const client = new Daytona({ apiKey: env.DAYTONA_API_KEY });
const sandbox = await client.create();
const setupAgent = await init({ sandbox: daytona(sandbox, { cleanup: true }), model: 'openai/gpt-5.5' });
const setup = await setupAgent.session();
await setup.shell(`git clone ${payload.repo} /workspace/project`);
await setup.shell('npm install', { cwd: '/workspace/project' });

const projectAgent = await init({ id: 'project', sandbox: daytona(sandbox), cwd: '/workspace/project', model: 'openai/gpt-5.5' });
const session = await projectAgent.session();
return await session.prompt(payload.prompt);

Remote MCP tools

const github = await connectMcpServer('github', {
  url: 'https://mcp.github.com/mcp',
  headers: { Authorization: `Bearer ${env.GITHUB_TOKEN}` },
});
const agent = await init({ model: 'anthropic/claude-sonnet-4-6', tools: github.tools });

connectMcpServer() defaults to modern streamable HTTP. For legacy SSE servers, pass transport: 'sse'. Flue does not auto-detect transports, spawn local stdio MCP servers, or handle OAuth callbacks in this first version.

Agents and sessions

Every agent invocation runs inside an initialized agent runtime. For HTTP agents, the agent ID is the last path segment:

POST /agents/<agent-name>/<id>

By default, agent.session() opens the default session for that agent ID. Reuse the same agent ID to continue the same default conversation. Use a new agent ID to start fresh.

Agents own sandbox state such as files written during a run. Sessions persist message history and conversation metadata inside an agent. On Cloudflare, session data is backed by Durable Objects and survives across requests. On Node.js, sessions are stored in memory by default unless you provide a custom store.

Tasks (subagents)

Use session.task() to run a focused, one-shot child agent in a detached session. Tasks share the same sandbox/filesystem, but get their own message history and discover AGENTS.md plus .agents/skills/ from their working directory. The same task tool is also available to the LLM during prompt() and skill() calls, so the agent can delegate parallel research or exploration work itself.

Roles

Roles can be set at the agent, session, or call level. Precedence is call role > session role > agent role. Role instructions are applied as call-scoped system prompt overlays, not injected into the persisted user message history.

Custom virtual sandboxes (raw just-bash)

import { Bash, InMemoryFs } from 'just-bash';
const fs = new InMemoryFs();
const agent = await init({
  sandbox: () => new Bash({ fs, cwd: '/workspace', python: true }),
  model: 'anthropic/claude-sonnet-4-6',
});

Running agents

• flue dev --target node / --target cloudflare — long-running watch-mode dev server. Default port 3583 ("FLUE" on a phone keypad).
• flue run <agent> — production-shaped one-shot invocation, perfect for CI.
• flue build --target node / --target cloudflare — builds to ./dist for deploy. Cloudflare and any Node.js host supported today.
• --env <path> flag (repeatable, later wins, shell env wins over file).
• flue dev --target cloudflare requires wrangler as a peer dep; for Cloudflare, flue build produces an unbundled TS entry that wrangler deploy bundles.