The Astro Team Secretly Built the Best AI Agent Framework

📋 Overview

Flue is an open-source framework built by the co-founder of Astro that takes Claude Code's agent harness concept and makes it 100% programmable. Built on top of Pi (the same minimal agent core behind OpenCode), it gives developers sessions, tools, skills, and sandboxed environments out of the box — all controllable from a single TypeScript file. Its killer feature: an in-memory virtual sandbox powered by Vercel's just-bash that avoids spinning up real containers, making it drastically cheaper to run fleets of agents at scale.

1 What Is Flue?

▶ 0:00

Flue is an open-source framework for building AI agents that takes what Claude Code does as a harness and makes it 100% programmable. Out of the box, it supports:

• Skills — reusable, structured instructions the agent can reference
• Tools — custom functions the agent can call
• Sandboxes — isolated execution environments
• Sessions — persistent conversation state

With just a few lines of TypeScript, you can create a fully-featured agent harness and deploy it anywhere — Node.js, Cloudflare Workers, or any other platform.

2 Origin Story — From Astro's Internal Tool

▶ 0:33

Flue was built by Fred K. Schott, co-founder of Astro. The team didn't set out to build a framework — they built Flue to run AI workflows inside Astro's own GitHub repo. When an engineer from Amplitude got their hands on it, they realized this was a tool every agent developer should have access to.

3 Built on Pi — The Agent Core

▶ 1:11

Flue is built on top of Pi, a minimal agent harness — the same core that OpenCode is built on. Flue wraps a real framework around Pi's agent core, adding:

• Custom tools via MCP servers
• Agent.md files for system-level instructions (like Claude Code's CLAUDE.md)
• Sandbox support by default
• Reusable skills with structured inputs

The analogy to Claude Code is direct: underneath Claude Code's terminal UI is a harness with tools, skills, sandboxes, and MCP support. Flue gives you that same harness, but headless and programmable.

4 Agents vs Workflows — No Human Required

▶ 1:32

A key distinction in Flue: agents vs workflows.

• Agents — like Claude Code, they assume a human behind the wheel driving the interaction. You export the agent object and connect to it interactively.
• Workflows — fully autonomous processes that don't require a human at all. You export a run function that initializes the agent, opens a session, and executes programmatically.

This makes Flue suitable for both interactive agents and headless agentic processes — CI/CD integrations, background tasks, batch processing pipelines.

5 Getting Started — Setup & Config

▶ 1:59

Setting up a Flue project requires three steps:

• Install the Flue runtime — what your agent imports and runs on
• Install the Flue CLI — compiles and serves your agent
• Set up an API key — from any provider Pi supports (Anthropic, OpenAI, etc.)

Then run flu init with a target, which creates a flu.config.ts file. The config uses Vite behind the scenes and supports two targets:

• Node — HTTP server on top of Hono
• Cloudflare — deploys to a Worker with a Durable Object for persistence

6 Building a Basic Agent

▶ 2:55

A basic Flue agent is remarkably minimal — just set a model and add instructions (which append to the system prompt). That's it.

To run it: flu connect builds and runs the agent. You specify:

• Agent name — matches the .ts file name
• Instance ID — unique identifier, useful when running multiple agents. On Cloudflare, this maps to a Durable Object instance.

The CLI loads the config, reads the target, and runs the agents it finds. If an agent.md file exists, it uses that as additional context. The output includes streaming responses, final JSON with text, token counts, cost, and model info.

7 Building a Workflow with Skills

▶ 4:11

The demo builds a workflow that generates YouTube title ideas and scores them. Key components:

• Agent with skills — a skill is imported with a skillInput attribute, providing structured capabilities
• Typed context — FluxContext type provides type-safe payload access (changing path to file causes a TypeScript error)
• Exported run function — instead of exporting the agent directly, workflows export a function that initializes the agent and opens a session

Project Structure

• Agents live in the agents/ directory
• Workflows live in the workflows/ directory
• Skills live in the skills/ directory

Run with: flu run <workflow-name> followed by the target and a JSON payload.

8 Sandbox vs Local Execution

▶ 5:31

By default, Flue runs agents in a sandbox using just-bash. The agent only has access to skill descriptions registered in the code — not the actual files on the filesystem.

This became apparent in the demo when the agent tried to find the Python skill file but couldn't access it. The fix: import local from flu/runtime/node, which tells Flue to run on the local system with full file access.

• Sandbox mode (default) — isolated, secure, but limited file access
• Local mode — full filesystem access, can run Python scripts, but less secure
• Working directory can be set to the skill's directory so the agent finds files immediately

9 Custom Tools — The Secure Alternative

▶ 6:22

If you don't want to give the agent full local system access, you can create custom tools instead:

• Load the Python file in the skill definition
• Create a tool (e.g., scoreTitle) with Valibot for parameter validation
• Register the tool inside the agent

This way, the agent stays sandboxed but gains specific capabilities through well-defined tool interfaces — the same pattern Claude Code uses with MCP tools.

10 HTTP API & Deployment

▶ 6:43

To expose the workflow via HTTP, just add the root middleware. Then:

• Build with flu build, specify target and port
• Run the generated server.js file — it inlines all agents and workflows
• Trigger via curl -X POST with workflow name and JSON data
• Check results via GET /workflows/:id

The compiled server.js is a single file containing everything — deploy it anywhere that supports Node.js. Flue also supports WebSockets for streaming workflow progress.

11 Flue vs Mastra

▶ 7:45

How does Flue compare to Mastra, another popular open-source AI agent framework?

• Mastra — more granular, step-by-step approach. You manually set up sessions, memory, sandbox, and tool loading yourself.
• Flue — harness-first approach. It assumes you'll need sessions, tools, skills, and sandboxes from the start, so they're all built in.

The philosophical difference: Mastra gives you building blocks to assemble; Flue gives you a working harness to customize.

12 The Sandbox Trick — Just Bash in Memory

▶ 8:16

Flue's most clever technical trick: each agent gets its own sandbox by default, but instead of spinning up a real container, it uses Vercel's just-bash — a re-implementation of Bash in TypeScript that runs entirely in memory.

• In-memory sandbox — no container boot-up time, no Linux machine overhead
• Built-in tools — grep, glob, and file read are available without a real filesystem
• Dramatically cheaper — run thousands of agents for next to nothing
• Opt-in real containers — supports Daytona, Cloudflare sandboxes, or any sandbox via URL when you need full isolation

Additional Features Mentioned

• Agent profiles — reusable agent configurations
• Daytona & Cloudflare sandboxes — or any sandbox accessible via URL
• Custom routes — for auth, health checks, etc.
• Sub-agents — agents that spawn other agents

🎯 Key Takeaways

🔗 Resources & Links

• Flue Framework — official site and documentation
• Announcement Tweet — Fred K. Schott's launch post on X
• Mastra overview — Better Stack's previous video on Mastra for comparison

⏱ Timestamp Index