Flue Harness-First AI Agent Framework

Last updated: 4 June 2026

Design and deploy a fully programmable AI agent or workflow — with sandboxes, skills, and tools — in a few lines of TypeScript, without manually wiring sessions, memory, or tool loading.

// TL;DR

Flue Harness-First AI Agent Framework is a TypeScript framework for building fully programmable AI agents and workflows in just a few lines of code. It provides sandboxes, skills, tools, sessions, and persistence out of the box — no manual wiring. Use it when you need real tool execution, reusable skills, in-memory or container sandboxes, and HTTP/WebSocket triggering. Choose Flue over granular frameworks when you want a harness-first setup that wraps infrastructure around your LLM automatically, similar to how Claude Code wraps a harness around its model.

Framework

// When should I use the Flue Harness-First AI Agent Framework?

Use this skill when you need to build an AI agent or automated workflow that requires real tools, reusable skills, sandbox execution, or HTTP/WebSocket triggering — especially when you want a harness-first setup rather than a granular, step-by-step configuration process.

// What inputs does Flue need to build an AI agent or workflow?

agent_or_workflow_goalrequired
What the agent or workflow must accomplish — e.g. 'generate ranked YouTube titles from a script file'
interaction_moderequired
Whether the agent requires human-in-the-loop input or runs fully autonomously as a workflow
deployment_targetrequired
Node (HTTP server via Hono) or Cloudflare (Worker + Durable Object for persistence)
llm_providerrequired
The AI provider API key to use — any provider supported by Pico (e.g. Anthropic)
skills_or_tools_needed
Any reusable skills (skill.md + backing scripts) or custom tools (code-defined) the agent needs
sandbox_requirement
Whether the agent needs a real container sandbox or can run on the in-memory just-bash default

// What are the core design principles behind Flue?

Harness-First Design

Flue assumes you will use sandboxes, skills, tools, and sessions from the start — you do not manually wire them. The framework wraps a real harness around Pico's agent core the same way Claude Code wraps a harness around its model, so every agent gets that infrastructure out of the box.

Agents vs. Workflows

Agents are interactive and support human-in-the-loop input; workflows export a `run` function, initialise the agent programmatically, and execute without requiring a human at all. Choose the right primitive for your use case: agent for conversational or driven processes, workflow for specific, repeatable agentic processes that don't need to change much.

In-Memory Sandbox by Default (just-bash)

Every agent runs in a sandbox powered by just-bash — a TypeScript re-implementation of bash that runs in memory instead of a real container. This gives access to grep, glob, and read tools without paying for a container boot every time, allowing thousands of agents to run for next to nothing. Opt into a real container only when you actually need one.

Skills vs. Tools

A skill is a reusable, file-based capability registered via a skill.md description; the agent discovers and invokes it. A tool is a code-defined, programmatically registered capability (e.g. a Python script wrapped with Valibot parameter validation). Use skills for human-readable, composable instructions; use tools when you need tight parameter contracts or want to avoid exposing local files to the sandbox.

Instance ID and Durable Persistence

Every running agent is given a unique instance ID. When deploying to Cloudflare, this ID maps directly onto its own Durable Object instance, giving each agent isolated persistent state. On Node, the same ID enables managing multiple concurrent agent sessions.

Local vs. Sandboxed Execution Trade-off

By default the sandbox cannot access your local file system. Importing `local` from `flue-runtime-node` grants the agent access to local files and runtimes (e.g. Python scripts), but removes isolation. The secure alternative is to wrap local assets as custom tools so the agent never touches the file system directly.

// How do you build and deploy a Flue agent step by step?

1
Install the Flue runtime and Flue CLI
The runtime is what your agent imports and executes on; the CLI compiles, packages, and serves your agent. Set up your LLM provider API key at this stage.
2
Run `flue init` with a deployment target
Choose Node (HTTP server via Hono) or Cloudflare (Worker + Durable Object). This generates a `flue.config.ts` file that tells the CLI how to package your project. Cloudflare target enables automatic persistence via Durable Objects; Node target gives you a portable server.mjs output.
3
Decide: Agent or Workflow?
If the process needs human-in-the-loop interaction, build an Agent (export the agent directly). If the process is specific, repeatable, and fully autonomous, build a Workflow (export a `run` function that initialises the agent and opens a session, receiving a typed payload). Place agents in the `agents/` directory, workflows in the `workflows/` directory.
4
Define the agent with a model and instructions
Set the model (any Pico-supported provider) and write instructions — these append to the system prompt. Optionally include an `agent.md` file at the project root for persistent system context. Keep instructions precise; for workflows, instruct the agent to use specific skills or tools.
5
Identify and register Skills and/or Tools
Skills live in the `skills/` directory at the project root and are registered via a skill input attribute on the agent. Each skill has a `skill.md` description the agent reads. Tools are code-defined: load the backing script, validate parameters with Valibot, and register the tool on the agent. Prefer tools over local file access when security isolation matters.
6
Decide on sandbox strategy
Default: in-memory just-bash sandbox (free, fast, no container cost). Use this unless you need real OS capabilities. If you need local file access or to run external runtimes (e.g. Python), import `local` from `flue-runtime-node` and set the working directory explicitly — but accept the loss of isolation. If you need full container isolation cheaply, opt into a real sandbox (Daytona, Cloudflare sandbox, or any URL-specified sandbox) only for those agents.
7
Run and test with `flue connect` (agents) or `flue run` (workflows)
For agents: `flue connect <agent-name> --instance <id>` — instance ID can be any string. For workflows: `flue run <workflow-name> --target <target> --payload '<json>'`. Inspect the final JSON output: it includes response text, input/output token counts, cost, and model used.
8
Enable HTTP or WebSocket triggering (optional)
Add the root middleware to your project. Then build the Flue project specifying target and port. The output `server.mjs` inlines all agents and workflows — deploy this single file anywhere Node.js is supported. Use HTTP POST to trigger workflows and GET to poll workflow status. Use WebSockets instead of HTTP if you need to stream workflow results.
9
Deploy to target environment
Node target: run server.mjs on any Node-compatible host. Cloudflare target: deploy to a Cloudflare Worker; each instance ID gets its own Durable Object for isolated persistence. Add custom routes for auth or health checks as needed.

// What are real-world examples of Flue agents and workflows?

A content team wants to auto-generate ranked title options from a script file, triggered by a CI/CD pipeline with no human interaction.

Build a Workflow (not an Agent) that exports `run`, receives the script file path as a typed payload, and passes it as the prompt. Register a skill in `skills/` backed by a scoring script. Because the scoring script is a local file, either use `local` from `flue-runtime-node` and set the working directory to the skill folder, or wrap the script as a custom tool with Valibot-validated parameters. Trigger via HTTP POST after building with the Node target.

A developer wants a conversational coding assistant that can read files, run commands, and accept follow-up instructions interactively.

Build an Agent (not a Workflow) with an `agent.md` for persistent context and relevant tools registered. Use `flue connect` with a stable instance ID. The default in-memory just-bash sandbox provides grep, glob, and read without container cost; opt into a real container sandbox only if the agent needs to install packages or run isolated processes.

A platform needs to run thousands of lightweight document-processing agents concurrently at minimal cost.

Use the default just-bash in-memory sandbox for all agents — no container boot cost, no per-agent infrastructure charge. Define each agent's scope via skills and tools. Assign unique instance IDs per job. Deploy to Cloudflare Workers with Durable Objects for stateful persistence per instance. Only agents that require real OS-level operations opt into a URL-specified real container sandbox.

// What mistakes should I avoid when using Flue?

Forgetting that the default just-bash sandbox has no access to your local file system — skills that rely on local scripts will silently fail to find their files unless you use `local` from `flue-runtime-node` or wrap the assets as a custom tool.
Placing agents or workflows in the wrong directory — agents must be in `agents/`, workflows in `workflows/`, and skills in `skills/` from the project root; Flue's CLI resolves paths based on this convention.
Using a Workflow when you need human-in-the-loop interaction, or an Agent when the process is fully automated — choose the correct primitive up front, as the export shape and session management differ.
Skipping `flue init` or misconfiguring the target — the `flue.config.ts` file is required for the CLI to know how to package the project; missing it breaks the build pipeline.
Using `local` from `flue-runtime-node` without setting the current working directory to the correct skill folder — the agent will search for files and fail, wasting tokens and time.
Reaching for a real container sandbox by default when the in-memory just-bash sandbox is sufficient — this adds unnecessary boot latency and cost; opt into real containers only when the agent genuinely requires full OS capabilities.
Manually wiring sessions, memory, and tool loading the way you would in a more granular framework like Mastra — Flue's harness-first design handles this; fighting the framework adds complexity it was designed to eliminate.

// What do Flue-specific terms like harness, just-bash, and Pico mean?

Harness: The infrastructure layer that wraps an LLM — providing skills, tools, sandbox execution, session management, and system prompt injection — enabling the model to do real work. Flue gives you a full harness in a few lines of TypeScript.
Agent: A Flue primitive that sets a model and instructions and supports human-in-the-loop interaction. Exported directly from its file; invoked with `flue connect`.
Workflow: A Flue primitive for fully autonomous, repeatable agentic processes. Exports a `run` function that programmatically initialises the agent, opens a session, and accepts a typed JSON payload; invoked with `flue run`.
Skill: A reusable, file-based agent capability. Lives in the `skills/` directory, described via a `skill.md` file the agent reads. Registered on the agent via a skill input attribute.
Tool: A code-defined, programmatically registered capability. Parameters are validated with Valibot; the tool wraps an external script or function. Preferred over skills when you need parameter contracts or want to avoid exposing local files to the sandbox.
just-bash: Vercel's TypeScript re-implementation of bash that runs in memory rather than a real container. Flue's default sandbox — provides grep, glob, and read capabilities at near-zero cost, with no container boot time.
Sandbox: The isolated execution environment each agent runs in by default (just-bash, in-memory). Can be upgraded to a real container (Daytona, Cloudflare sandbox, or any URL-specified sandbox) only when full OS capabilities are required.
Instance ID: A unique string identifier assigned to each running agent. Enables managing multiple concurrent sessions; maps directly onto a Cloudflare Durable Object instance when deploying to the Cloudflare target.
Pico: The minimal agent harness core that Flue is built on top of — the same core underlying Open Claude. Flue wraps a real framework around Pico's agent core.
Flue Config (flue.config.ts): The project configuration file generated by `flue init`. Tells the CLI the deployment target (Node or Cloudflare) and how to package the project. Uses Vite under the hood.
Agent Profile: A Flue feature for defining reusable agent configurations that can be shared across multiple agents or workflows without duplication.
Root Middleware: A single addition that enables HTTP and WebSocket triggering of agents and workflows, exposing them via a built server.mjs file deployable anywhere Node.js runs.
Durable Object: A Cloudflare primitive that Flue maps each agent instance ID onto when deploying to the Cloudflare target, providing isolated persistent state per agent instance.
local (flue-runtime-node): An import from `flue-runtime-node` that instructs Flue to run the agent on the local system rather than in the default sandbox, granting access to local files and runtimes at the cost of isolation.

// FREQUENTLY ASKED QUESTIONS

What is the Flue AI agent framework?

Flue is a harness-first TypeScript framework for building AI agents and workflows that provides sandboxes, skills, tools, session management, and persistence out of the box. Built on top of Pico (the same core behind Open Claude), it wraps a full infrastructure harness around your LLM so you can define agents in a few lines of code without manually wiring sessions, memory, or tool loading. It supports deployment to Node.js or Cloudflare Workers.

What is just-bash in Flue?

Just-bash is Vercel's TypeScript re-implementation of bash that runs entirely in memory rather than in a real container. It is Flue's default sandbox, providing grep, glob, and read capabilities at near-zero cost with no container boot time. This allows you to run thousands of agents concurrently without paying for container infrastructure. You only opt into a real container sandbox when your agent genuinely requires full OS-level capabilities.

How do I create an AI agent with Flue?

Install the Flue runtime and CLI, run `flue init` to select a deployment target (Node or Cloudflare), then create an agent file in the `agents/` directory. Define your agent with a model and instructions, optionally register skills or tools, and test with `flue connect <agent-name> --instance <id>`. The framework handles sandboxing, session management, and tool loading automatically.

How do I build a workflow in Flue instead of an agent?

Create a file in the `workflows/` directory that exports a `run` function. This function programmatically initializes the agent, opens a session, and accepts a typed JSON payload. Trigger it with `flue run <workflow-name> --target <target> --payload '<json>'`. Workflows are fully autonomous — no human interaction needed — and are ideal for repeatable agentic processes triggered by CI/CD, HTTP POST, or scheduled jobs.

How does Flue compare to Mastra or LangChain for building AI agents?

Flue takes a harness-first approach — sandboxes, skills, tools, and sessions are wired automatically, so you write less configuration code. Frameworks like Mastra and LangChain offer granular, step-by-step configuration where you manually wire each component. Flue is better when you want infrastructure wrapped around your LLM out of the box; granular frameworks are better when you need fine-grained control over every pipeline step.

When should I use Flue instead of building my own agent setup?

Use Flue when you need real tool execution, reusable skills, sandbox isolation, or HTTP/WebSocket triggering and don't want to manually wire sessions, memory, and tool loading. It's especially valuable when deploying many concurrent agents at low cost using the in-memory just-bash sandbox, or when you need per-agent persistent state via Cloudflare Durable Objects. Skip it if you only need a simple chat wrapper.

What results can I expect after deploying a Flue workflow?

After deploying a Flue workflow, you get a single `server.mjs` file that inlines all agents and workflows, deployable anywhere Node.js runs. Workflow runs return structured JSON output including the response text, input/output token counts, cost, and model used. You can trigger workflows via HTTP POST and poll status via GET, or stream results over WebSockets for real-time output.

What's the difference between skills and tools in Flue?

Skills are file-based, reusable capabilities described via a `skill.md` file in the `skills/` directory — the agent reads the description and invokes them. Tools are code-defined capabilities registered programmatically with Valibot parameter validation. Use skills for human-readable, composable instructions. Use tools when you need strict parameter contracts or want to avoid exposing local files to the sandbox.

Can Flue agents access my local file system?

By default, no — the just-bash sandbox cannot access your local file system. To grant access, import `local` from `flue-runtime-node` and set the working directory explicitly, but this removes isolation. The more secure alternative is wrapping local assets as custom tools with Valibot validation, so the agent never touches the file system directly. Choose based on your security requirements.

How do I deploy a Flue agent to Cloudflare?

Run `flue init` and select the Cloudflare target. Build your project, and each agent's instance ID maps directly onto a Cloudflare Durable Object, giving isolated persistent state per agent. Deploy the output as a Cloudflare Worker. This approach is ideal for running thousands of stateful agents concurrently, since each gets its own persistence without shared infrastructure.

// GET STARTED

Turn Any YouTube Video Into An AI Skill

SkillForge captures a creator's exact methodology from their video and turns it into a reusable AI skill you can invoke in Claude, ChatGPT, or any LLM.

Forge your own skill