E2B

E2B 适配器将已初始化的 E2B 沙箱（来自 e2b 包）适配为 Flue 的沙箱接口。当智能体需要在应用主机之外运行 shell 命令和管理工作区文件时，可使用它进行提供商管理的 Linux 执行。

快速开始

使用 E2B 蓝图为现有 Flue 项目添加提供商管理的 Linux 沙箱能力。在终端或你选择的编码智能体中运行以下命令：

flue add sandbox e2b

概述

蓝图会在需要时安装 e2b，并在你的源码根目录下创建 sandboxes/e2b.ts。该文件适配你的应用已经创建的 E2B 沙箱；它不会创建、保留或关闭提供商资源。

// flue-blueprint: sandbox/e2b@1
import { sandboxFromDriver, useModel } from '@flue/runtime';
import type { SandboxDriver, SandboxFactory, Sandbox, FileStat } from '@flue/runtime';
import type { Sandbox as E2BSandbox } from 'e2b';

class E2BSandboxDriver implements SandboxDriver {
  constructor(private sandbox: E2BSandbox) {}

  /* 使用 sandbox.files 实现文件读写、stat、列表、存在检查和 mkdir。 */

  /* 在调用 sandbox.files.remove() 前拒绝递归或 force 选项。 */

  /* 使用 sandbox.commands.run() 实现 exec()，原样转发 timeoutMs。 */
}

export function e2b(sandbox: E2BSandbox): SandboxFactory {
  return {
    async createSandbox(): Promise<Sandbox> {
      const sandboxCwd = '/home/user';
      const driver = new E2BSandboxDriver(sandbox);
      return sandboxFromDriver(driver, sandboxCwd);
    },
  };
}

将已初始化的 E2B Sandbox 传递给 e2b(...)，然后将返回的工厂传递给智能体的 useSandbox(...) 调用。Flue 从 /home/user 解析工作区路径，通过会话操作暴露 E2B 的文件和命令，原样转发毫秒级命令超时，并仅报告 E2B 暴露的文件元数据。E2B 的直接删除 API 没有递归或强制控制，因此适配器会在删除前拒绝这两个选项。你的应用仍然负责沙箱配置和生命周期。

配置

生成的适配器期望你的应用创建并配置 E2B 沙箱。它不会为你决定沙箱的身份、镜像或生命周期。

典型用法

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

export function Assistant() {
  useModel('anthropic/claude-sonnet-4-6');
  useSandbox({
    // 按照 SandboxFactory 契约，延迟执行：构造此对象成本很低；
    // 昂贵的 E2B 沙箱创建只在 createSandbox() 内部的初始化阶段
    // 执行一次 —— 永远不会在重新渲染时执行。
    async createSandbox(options) {
      const sandbox = await Sandbox.create();
      return e2b(sandbox).createSandbox(options);
    },
  });
}

E2B 支持模板、超时和元数据。在将沙箱传递给 e2b(...) 之前配置它们。要使用更窄的工作目录，请在智能体的 useSandbox(...) 调用上配置 cwd；Flue 会在 init() 期间针对适配器的提供商拥有的基础目录解析它一次。

参见沙箱、沙箱适配器 API 和 E2B 文档。