# Flue: A TypeScript harness framework for building autonomous agents

> Flue is a framework for building agents with TypeScript that provides sandboxes, tools, skills, and durable sessions. Agents are functions that receive a model, environment, and tools and autonomously work toward goals.

**withastro/flue** — The sandbox agent framework.

- Repository: https://github.com/withastro/flue
- Website: https://www.flueframework.com
- Stars: 8,407 · Forks: 503
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/withastro-flue

## From chatbots to autonomous agents

Agents have evolved in stages. The first agents were built with raw LLM API calls, which worked for simple chatbots and scripted tasks but not much else. These early agents required you to engineer every interaction: dictate the steps, handle the output, feed it back to the API. Agents like Claude Code and Codex broke the mold by being truly autonomous: you give them a task, not pre-defined steps, and trust them to complete it using context and tools. These agents could reason, use tools, read files, make decisions, and iterate. Flue unlocks this architecture for any team. Its built-in TypeScript harness gives any model the context and environment it needs for truly autonomous work: sessions, tools, skills, instructions, filesystem access, and a secure sandbox. You run agents locally via CLI during development or deploy them to your hosted runtime of choice when you are ready to scale. This removes the friction of building agents: you no longer need to manage API calls directly or handle threading state.

## Agents as TypeScript functions

In Flue, the agent IS the function. You define agents using TypeScript directives like useModel, useSandbox, useSkill, and useTool. Each directive composes a piece of the agent's harness. The agent function is marked with 'use agent' to tell the framework it should be treated as an agent, not a regular function. The README shows an example: import a skill from a markdown file, set the model to claude-sonnet-4-6, add a local sandbox, and compose tools like openIssue and searchCode from your codebase. Each call to a directive adds to the agent's capabilities.

Here is the example from the README:

```ts
'use agent';
import { useModel, useSandbox, useSkill, useTool } from '@flue/runtime';
import { local } from '@flue/runtime/node';
import triage from '../skills/triage/SKILL.md';
import verify from '../skills/verify/SKILL.md';
import { openIssue, searchCode } from '../tools/github.ts';

export function Triage() {
  useModel('anthropic/claude-sonnet-4-6');
  useSandbox(local());
  useSkill(triage);
  useSkill(verify);
  useTool(openIssue);
  useTool(searchCode);
}
```

This is the entire agent definition. Each directive specifies one piece: the model, the sandbox environment, the skills, and the available tools. The framework assembles these into a complete agent harness.

## Sandboxes, skills, and tools

Flue provides three core abstractions that make autonomous agents practical. Sandboxes give agents a secure environment where they can use tools, modify files, and autonomously complete real work without risking the host system. Sandboxes can be local (running on the developer machine), virtual, or remote; Flue handles sandboxing via integrations with platforms like Daytona. Skills are reusable instructions and prompts written in markdown files that agents load with useSkill. Skills package domain knowledge and workflows, so you can compose expertise without rewriting it for each agent. Tools are TypeScript functions that agents call to interact with external systems: calling APIs, querying databases, or triggering actions. The framework handles connecting agents to sandboxes and tools safely, preventing unauthorized access while giving agents the capability to do real work. The README documents MCP Servers as another integration point, allowing agents to connect to authenticated tools and services through the open Model Context Protocol ecosystem.

## Durability and sessions

Flue agents maintain continuity across conversations and events as they autonomously work toward a goal. Sessions allow agents to remember context and state across multiple invocations, so an agent can pick up where it left off after a restart or failure. This durability is essential for agents that need to coordinate work across multiple days or multiple user interactions without losing progress. The README names durability as a core feature: agents preserve progress through failures and restarts with durable recovery for accepted work, meaning the framework tracks what the agent has completed and prevents it from repeating work. The framework also provides persistence adapters, including @flue/postgres, for storing agent state in a database. The framework handles session management transparently, letting you focus on what the agent should accomplish rather than how to thread state through API calls.

## Connecting to existing systems

Agents built with Flue connect to the systems where work already happens. You define tools that call your APIs, repositories, databases, or other services. The framework provides a model-agnostic API, so you can swap models without rewriting your agent harness. This means your agent code stays stable even as you upgrade to newer or different models. Flue also provides a channels feature that lets agents receive verified events from Slack, Teams, Discord, GitHub, and other platforms. This means agents can be triggered by events in your workflow tools and can send responses back to those same platforms, integrating into existing team processes.

## Writing agent functions with TypeScript directives

Flue agents are created as TypeScript functions with the 'use agent' directive at the top, which tells the framework to treat it as an agent rather than a regular function. You then import directives from @flue/runtime: useModel sets the LLM to use (the example uses anthropic/claude-sonnet-4-6), useSandbox configures the execution environment (the @flue/runtime/node package provides the local() sandbox for local development), useSkill loads reusable instructions from markdown files, and useTool adds capabilities by referencing TypeScript functions from your codebase. The root package.json shows Flue requires Node.js 22 or later and pnpm 11 or later, and the @flue/runtime package is available from the packages/ directory in the monorepo. Each directive call adds one piece to the agent's harness. The README shows importing both skills (triage and verify) and tools (openIssue and searchCode) in the same function, letting you compose domain knowledge and capabilities together.

## Running agents locally or in the cloud

Flue agents can run locally via CLI during development, or you can deploy them to a hosted runtime of your choice. The framework supports multiple deployment targets: Node.js, Cloudflare Workers, GitHub Actions, GitLab CI/CD, Daytona, and Render. This flexibility lets you start developing agents on your machine and scale to production without rewriting the agent code. The framework handles the differences in sandbox environment and deployment target across platforms. The @flue/cli package provides the CLI binary for local runs, blueprints, and offline documentation. The @flue/vite package provides a Vite plugin that lets you run `vite dev` and `vite build` for Node.js and Cloudflare deployments, simplifying the build process. The @flue/sdk package is a client SDK for consuming deployed agent conversations from your applications. You can test agents locally, iterate on their behavior, and then deploy the same agent code to production with different configuration. The framework also provides observability through @flue/opentelemetry for OpenTelemetry integration, letting you export telemetry to Braintrust, Sentry, or your own observer.

## Conclusion

Flue suits teams building autonomous agents who want to compose agents from tools and skills without managing raw LLM API calls. It is most useful when you need agents that maintain continuity across sessions and can safely use sandboxes and tools. Start by installing Flue and writing an agent function with useModel, useSandbox, and useSkill directives.

## FAQ

### What is an agent framework?

An agent framework provides tools and abstractions for building autonomous systems that can perceive their environment, make decisions, and take action toward goals. Flue provides sandboxes, skills, tools, and session management.

### How do I build an agent with Flue?

Write a TypeScript function marked with 'use agent' directive. Use useModel to set the LLM, useSandbox to add a secure environment, useSkill to load prompts, and useTool to add capabilities.

### Can I run Flue agents locally?

Yes. Flue agents can run locally via CLI or deploy to a hosted runtime. This flexibility lets you develop on your machine and scale without rewriting code.

### What is a skill in Flue?

A skill is reusable instructions and prompts written in markdown that agents load with useSkill. Skills provide domain knowledge and procedures that guide agent behavior.

### Does Flue support multiple models?

Yes. Flue provides a model-agnostic API, so you can set any model with useModel and swap models without rewriting your agent harness.

## Sources

- [License: Apache-2.0](https://github.com/withastro/flue/blob/main/LICENSE)
- [Project website](https://www.flueframework.com)
- [README](https://github.com/withastro/flue/blob/main/README.md)
- [Releases](https://github.com/withastro/flue/releases)
- [withastro/flue on GitHub](https://github.com/withastro/flue)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/withastro-flue