Documentation

Flue is a TypeScript agent framework from the Astro team. An agent is a function marked with 'use agent' and configured with React-like hooks: useModel() picks the LLM, useSandbox() attaches a workspace. That second hook is what gives the agent its read, write, edit, bash, grep, and glob tools — without it the agent has no filesystem and no shell at all. Flue’s E2B adapter points those tools at an E2B sandbox. It ships as a blueprint: flue add sandbox e2b prints a Markdown implementation guide that your coding agent applies, leaving the adapter in your repo as src/sandboxes/e2b.ts. There is no @e2b/flue package — the only E2B dependency is the e2b SDK.

Flue adapters are deliberately thin. Your application creates the E2B sandbox and decides when it dies; Flue wraps the handle you hand it and never destroys provider infrastructure.

Why E2B as the sandbox

Flue ships two built-in environments — an in-memory just-bash sandbox and local(), which binds the agent to your host.

	E2B	`bash()` virtual sandbox	`local()`
Where commands run	Firecracker microVM in E2B’s cloud	Emulated in your Node.js process	Your host, as real processes
Isolation	Full VM boundary	No host access, but no real processes either	None, by design
Toolchain	Debian 12, `apt`, any runtime you install or bake into a template	The unix subset just-bash implements	Whatever the host already has
Filesystem lifetime	Lives with the sandbox: up to 24 hours running (1 hour on the Base tier), indefinitely once paused	Rebuilt empty every time the agent initializes	The host disk
Per-conversation workspaces	One sandbox keyed on the agent instance id	Ephemeral	Every conversation shares one host

Use E2B when agent-written code must not touch your host, when the work needs a real Linux toolchain, or when each conversation needs a workspace that outlives the process that started it.

Prerequisites

Node.js 22.19 or later
An E2B API key
A model provider key — this guide uses Anthropic

Create a project

Skip to the next section if you already have a Flue project.

mkdir flue-e2b-agent && cd flue-e2b-agent
npx @flue/cli@latest init . --target node
npm install
npm install e2b

flue init writes flue.config.ts, package.json, tsconfig.json, .env, src/agents/hello.ts, src/db.ts, AGENTS.md, and README.md. It does not install anything, hence the separate npm install. Put both keys in .env — flue run loads it automatically, and the E2B SDK reads E2B_API_KEY from the environment:

.env

E2B_API_KEY="e2b_***"
ANTHROPIC_API_KEY="sk-ant-***"

Add the adapter

npx flue add sandbox e2b --print | claude

flue add is not a package installer. It fetches the blueprint from Flue’s registry and prints it; the coding agent you pipe it into writes the file. Swap claude for codex, opencode, or whatever you use — or read the guide yourself with npx flue add sandbox e2b --print | less. Inside a coding agent session the CLI detects that and writes to stdout without --print. The result is src/sandboxes/e2b.ts, tagged // flue-blueprint: sandbox/e2b@1, exporting e2b(sandbox) — a SandboxFactory rooted at /home/user. It implements Flue’s SandboxDriver directly against the E2B SDK rather than shelling out:

Flue driver operation	E2B call
`readFile`, `writeFile`	`sandbox.files.read`, `sandbox.files.write`
`readdir`, `exists`, `stat`	`sandbox.files.list`, `.exists`, `.getInfo`
`mkdir`	`sandbox.files.makeDir` (always recursive on E2B)
`rm`	`sandbox.files.remove` — throws on `recursive` or `force`, which E2B’s direct remove API has no equivalent for
`exec`	`sandbox.commands.run`, with `timeoutMs` forwarded unchanged

To pull in a later revision of the adapter, pipe npx flue update sandbox e2b --print into your coding agent the same way; the marker comment is how the guide recognizes an existing install.

Write the agent

The factory is where you own the sandbox: create it with the E2B SDK, then hand it to e2b().

src/agents/analyst.ts

'use agent';
import { useModel, useSandbox } from '@flue/runtime';
import { Sandbox } from 'e2b';
import { e2b } from '../sandboxes/e2b.ts';

export function Analyst() {
	useModel('anthropic/claude-sonnet-4-6');

	useSandbox({
		// Lazy: createSandbox() runs once, when the runtime initializes the
		// agent — not on every render.
		async createSandbox(options) {
			const sandbox = await Sandbox.create({
				timeoutMs: 10 * 60_000,
				metadata: { framework: 'flue', agent: 'analyst' },
			});
			console.error(`[e2b] sandbox ${sandbox.sandboxId}`);
			return e2b(sandbox).createSandbox(options);
		},
	});

	return 'You work in a Linux sandbox. Use bash for anything about the machine or its files, and quote the exact command output in your answer.';
}

Two details that matter:

createSandbox is called once per agent initialization, never on a re-render. Creating the sandbox inside it — not in the module body — is what keeps one sandbox per conversation instead of one per render.
timeoutMs is E2B’s, not Flue’s. The default sandbox timeout is 5 minutes; a conversational agent usually wants more. Nothing in Flue extends it for you.

Run it

npx flue run src/agents/analyst.ts --message "Which Linux kernel is this box running, and how much free disk does /home/user have? Run the commands."

Flue streams tool activity to stderr and the final reply to stdout:

[e2b] sandbox ic1av8osjd5gtxrsegyfz
tool bash
tool done bash
  1. Linux Kernel: 6.1.158+
  2. Free Disk Space for /home/user: 22 GB total, 1.3 GB used, 20 GB available

The sandbox is now in your E2B dashboard. The metadata you set at creation is how you find it again from the SDK:

import { Sandbox } from 'e2b'

const [sandbox] = await Sandbox.list({
  query: { metadata: { framework: 'flue' }, state: ['running', 'paused'] },
}).nextItems()

console.log(sandbox.sandboxId, sandbox.state) // ic1av8osjd5gtxrsegyfz running

Keep the same sandbox across turns

Flue conversations persist across flue run invocations. Sandboxes do not, unless you make them: the default factory above creates a fresh one every time the agent initializes. createSandbox(options) receives options.id — the agent instance id — so store it in metadata and look it up first.

src/agents/durable.ts

'use agent';
import { useModel, useSandbox } from '@flue/runtime';
import { Sandbox } from 'e2b';
import { e2b } from '../sandboxes/e2b.ts';

export function Durable() {
	useModel('anthropic/claude-sonnet-4-6');

	useSandbox({
		async createSandbox(options) {
			// `options.id` is the agent instance id — key the sandbox on it so
			// the next message in this conversation gets the same workspace.
			const [existing] = await Sandbox.list({
				query: { metadata: { flueInstance: options.id }, state: ['running', 'paused'] },
			}).nextItems();

			// connect() never shortens the window; passing timeoutMs extends it
			// back to a full 10 minutes for this turn.
			const sandbox = existing
				? await Sandbox.connect(existing.sandboxId, { timeoutMs: 10 * 60_000 })
				: await Sandbox.create({
						timeoutMs: 10 * 60_000,
						metadata: { flueInstance: options.id },
					});

			console.error(`[e2b] ${existing ? 'reconnected' : 'created'} ${sandbox.sandboxId}`);
			return e2b(sandbox).createSandbox(options);
		},
	});

	return 'You work in a Linux sandbox at /home/user. Use bash.';
}

Two runs of the same conversation id now share one workspace, across separate processes:

npx flue run src/agents/durable.ts --id demo-1 --message "Write the text 'hello from turn one' to /home/user/note.txt, then confirm."
# [e2b] created ivk69fg95t9bndyf9odko

npx flue run src/agents/durable.ts --id demo-1 --message "cat /home/user/note.txt and quote it exactly."
# [e2b] reconnected ivk69fg95t9bndyf9odko
# > hello from turn one

Including 'paused' in the state filter covers longer gaps: Sandbox.connect() resumes a paused sandbox with its filesystem intact, so a conversation can go quiet for days and come back to the same disk. Reconnecting can only ever lengthen a sandbox’s window. connect() keeps whatever time is left and raises it to the requested timeout — the 5-minute default, or the timeoutMs you pass — when the remainder is shorter than that. A sandbox with 20 minutes left keeps its 20 minutes either way.

Use a custom template

Sandbox.create() takes a template name or ID as its first argument. Bake the language runtimes, system packages, and repo checkout your agent needs into a template so no turn is spent on apt-get:

const sandbox = await Sandbox.create('your-template-name', {
  timeoutMs: 10 * 60_000,
})

Lifecycle is your job

The adapter never creates or kills anything — it only wraps the sandbox you pass in. What that leaves you:

Timeout is the backstop. timeoutMs at creation decides how long an unattended sandbox lives; the sandbox dies at that point unless you pause it.
Nothing kills the sandbox when the agent finishes. flue run exits and the sandbox keeps running. Call sandbox.kill() from a harness tool, from your server’s teardown, or from a sweep keyed on metadata.

import { Sandbox } from 'e2b'

for (const sandbox of await Sandbox.list({
  query: { metadata: { framework: 'flue' }, state: ['running', 'paused'] },
}).nextItems()) {
  await Sandbox.kill(sandbox.sandboxId)
}

Troubleshooting

A failing command shows the agent only 'exit status 1'

The blueprint’s exec() calls sandbox.commands.run() without a try/catch, and the E2B SDK throws CommandExitError on any non-zero exit instead of returning a result. Flue turns that throw into a bare tool error, so the model sees <error>exit status 1</error> and never sees stderr.Unwrap the error into the result the SandboxDriver contract expects:

src/sandboxes/e2b.ts

import { CommandExitError } from 'e2b';

// inside E2BSandboxDriver.exec()
try {
  const result = await this.sandbox.commands.run(command, {
    cwd: options?.cwd,
    envs: options?.env,
    timeoutMs: options?.timeoutMs,
  });
  return {
    stdout: result.stdout ?? '',
    stderr: result.stderr ?? '',
    exitCode: result.exitCode ?? 0,
  };
} catch (error) {
  if (error instanceof CommandExitError) {
    return {
      stdout: error.stdout ?? '',
      stderr: error.stderr ?? '',
      exitCode: error.exitCode ?? 1,
    };
  }
  throw error;
}

The same cat of a missing file then reaches the model as cat: /home/user/does-not-exist.txt: No such file or directory plus the exit code — which is what it needs to fix its own command.

AuthenticationError: API key is required

AuthenticationError: API key is required, please visit the API Keys tab at
https://e2b.dev/dashboard?tab=keys to get your API key.

The E2B SDK reads E2B_API_KEY from process.env. flue run loads the project’s .env for you (--env <file> picks a different one). Anywhere else — a dev server, a built server, CI — put the key in the process environment yourself, or pass it explicitly with Sandbox.create({ apiKey: process.env.MY_KEY }).

ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX when importing the adapter

The blueprint’s driver class uses a TypeScript parameter property (constructor(private sandbox: E2BSandbox) {}), which Node.js’s built-in type stripping refuses to compile — including on Node 24:

ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX

flue run compiles the file properly, so agents are unaffected. A standalone script that imports the adapter directly needs node --experimental-transform-types.

rm fails with SandboxOperationUnsupportedError

SandboxOperationUnsupportedError: E2B does not support rm with "recursive".

E2B’s files.remove() has no recursive or force flags, so the adapter rejects both rather than silently ignoring them. When a tree has to go, let the agent run rm -rf through bash instead — that path goes through commands.run() and works.

How the integration works

Component	Responsibility
Flue runtime	Runs turns, persists the conversation, calls `createSandbox()` once per initialization
`useSandbox()`	Attaches the environment and adds the file and shell tools to the agent
Your factory	Creates or reconnects the E2B sandbox and owns its lifetime
`src/sandboxes/e2b.ts`	Maps Flue’s `SandboxDriver` onto `sandbox.files` and `sandbox.commands`
E2B template	Base OS, runtimes, and pre-installed dependencies

Learn more

Flue: Sandboxes guide — useSandbox(), the virtual sandbox, and local()
Flue: E2B adapter — the blueprint’s own reference page
Flue: Sandbox Adapter API — the SandboxDriver contract the adapter implements
flue add and flue run — the two CLI commands used here

Templates

Build custom sandbox templates with pre-installed dependencies

Sandbox persistence

Pause, resume, and manage sandbox lifecycle

JavaScript SDK

The e2b package the adapter is built on

Getting started

Use cases

Agents

Storage

Code interpreting

Sandbox

Templates

Network

Filesystem

Volumes

Commands

MCP gateway

CLI

Deployment

Migration

FAQ

Flue

Why E2B as the sandbox

Prerequisites

Create a project

Add the adapter

Write the agent

Run it

Keep the same sandbox across turns

Use a custom template

Lifecycle is your job

Troubleshooting

How the integration works

Learn more

Templates

Sandbox persistence

JavaScript SDK

​Why E2B as the sandbox

​Prerequisites

​Create a project

​Add the adapter

​Write the agent

​Run it

​Keep the same sandbox across turns

​Use a custom template

​Lifecycle is your job

​Troubleshooting

​How the integration works

​Learn more

​Related guides

Templates

Sandbox persistence

JavaScript SDK

Why E2B as the sandbox

Prerequisites

Create a project

Add the adapter

Write the agent

Run it

Keep the same sandbox across turns

Use a custom template

Lifecycle is your job

Troubleshooting

How the integration works

Learn more

Related guides