Skip to Content
FacetX

沙箱

📦

沙箱是 Agent 进行文件和命令操作的隔离工作区。它让 FacetX 能够采取真实行动，而不仅仅是对话。

沙箱为 Lead Agent 提供一个受控环境，在其中可以读取文件、写入输出、运行 Shell 命令并生成产出物。没有沙箱，Agent 只能生成文本；有了沙箱，它可以编写和执行代码、处理数据文件、生成图表并构建交付物。

沙箱模式

FacetX 支持四种沙箱模式，选择适合你部署的一种：

LocalSandbox（默认）

命令直接在主机机器的文件系统上运行，没有容器隔离。

  • 适合：受信任的单用户本地开发工作流。
  • 风险：Agent 可以访问主机文件系统。默认使用 allow_host_bash: false 防止任意命令执行。
sandbox:
  use: FacetX.sandbox.local:LocalSandboxProvider
  allow_host_bash: false # 默认；仅对完全受信任的工作流设置为 true

基于容器的 AIO 沙箱

命令在隔离容器中运行（Linux/Windows 上的 Docker，macOS 上的 Apple Container）。每个沙箱会话获得一个全新的容器环境。

  • 适合：多用户环境、生产部署，或任何需要执行隔离的场景。
sandbox:
  use: FacetX.community.aio_sandbox:AioSandboxProvider
 
  # 可选：容器镜像（下方显示默认值）
  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
 
  # 可选：最大并发容器数（默认：3，超出时 LRU 淘汰）
  replicas: 3
 
  # 可选：空闲超时（秒，默认：600）
  idle_timeout: 600
 
  # 可选：自定义挂载
  mounts:
    - host_path: /path/on/host
      container_path: /home/user/shared
      read_only: false

安装：cd backend && uv add 'FacetX-harness[aio-sandbox]'

E2B 云端沙箱

命令在 E2B  云端的 micro-VM 中执行。每个线程通过 metadata 绑定到一个独立的 e2b 沙箱，因此即使 Gateway 重启或在多进程之间，同一个 FacetX 线程也始终复用同一个 e2b 沙箱。当达到配置的空闲超时时，e2b 会自动回收云端 VM。

  • 适合：托管/Serverless 部署、不想自行运维 Docker 或 Kubernetes 的团队、开箱即用需要真实 Jupyter 内核的工作流。
  • 取舍：需要访问 e2b 控制面网络以及一个 API Key；挂载只能在沙箱启动时一次性上传（云端沙箱无法做主机 bind-mount）。
sandbox:
  use: FacetX.community.e2b_sandbox:E2BSandboxProvider
 
  # 必填：e2b API Key。若不写则回退读取环境变量 E2B_API_KEY。
  api_key: $E2B_API_KEY
 
  # 可选：e2b 沙箱模板 id（默认：code-interpreter-v1）
  template: code-interpreter-v1
 
  # 可选：自部署 e2b 实例的 domain
  # domain: e2b.dev
 
  # 可选：沙箱内部 /mnt/user-data 实际指向的目录（默认：/home/user）
  home_dir: /home/user
 
  # 可选：服务端强制的空闲超时（秒，默认 600，最大 86400）。
  # 每次 release 时 provider 会自动续期，让 warm 沙箱保持存活。
  idle_timeout: 600
 
  # 可选：单个 Gateway 进程内的最大并发沙箱数（默认：3）。
  # 超出时按 LRU 回收 warm 沙箱。
  replicas: 3
 
  # 可选：启动时一次性把主机文件上传到沙箱。
  # read_only 的目录在上传后会被 chmod 为只读。
  mounts:
    - host_path: /path/on/host
      container_path: /home/user/shared
      read_only: false
 
  # 可选：创建沙箱时传入的环境变量。
  # 以 "$" 开头的值会从主机环境变量解析。
  environment:
    OPENAI_API_KEY: $OPENAI_API_KEY

安装：e2b-code-interpreter 已经是 FacetX-harness 的核心依赖，无需额外安装 —— 只需配置 API Key，并在 config.yaml 中切换 provider 即可。

在 e2b.dev/dashboard  申请 API Key，然后在 config.yaml 中直接配置 sandbox.api_key，或在 .env 中导出 E2B_API_KEY。

因为 e2b 是远程沙箱，FacetX 的虚拟前缀 /mnt/user-data 会被自动重映射到云端 VM 的 home_dir（默认 /home/user）。 原本读写 /mnt/user-data/... 的工具无需任何改动即可正常工作。

Provisioner 管理的沙箱（Kubernetes）

每个沙箱在 Kubernetes 集群中获得一个专用 Pod，由 Provisioner 服务管理。这提供最强的隔离性，适合有多个并发用户的生产环境。

sandbox:
  use: FacetX.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

路径映射

沙箱使用路径映射来桥接主机文件系统和容器的虚拟文件系统。始终配置两个关键映射：

主机路径容器路径访问权限
skills/（来自 skills.path）/mnt/skills（来自 skills.container_path）只读
.facetx/threads/{thread_id}/user-data//mnt/user-data/读写

技能目录始终以只读方式挂载。线程将其工作数据（上传文件、输出、中间文件）写入 /mnt/user-data/。

自定义挂载

你可以为本地沙箱使用 mounts: 配置添加额外挂载：

sandbox:
  use: FacetX.sandbox.local:LocalSandboxProvider
  mounts:
    - host_path: /home/user/my-project
      container_path: /mnt/my-project
      read_only: true

自定义挂载的 container_path 不能与保留前缀冲突： /mnt/skills、/mnt/acp-workspace 或 /mnt/user-data。

当 LocalSandboxProvider 运行在生产 Docker（make up）中时，它实际运行在 facetx-gateway 容器里。此时 host_path 是从 gateway 容器的文件系统解析，而不是直接从 Docker 宿主机解析。需要先把宿主机目录 bind mount 到 gateway 服务，再在 config.yaml 中使用容器内路径：

# docker/docker-compose.yaml 或 override 文件
services:
  gateway:
    volumes:
      - ${FACETX_REPO_ROOT}/.facetx/knowledge:/app/.facetx/knowledge:ro
sandbox:
  use: FacetX.sandbox.local:LocalSandboxProvider
  mounts:
    - host_path: /app/.facetx/knowledge
      container_path: /mnt/knowledge
      read_only: true

如果配置的 host_path 对 gateway 进程不可见，FacetX 会记录错误日志并忽略该挂载。

输出截断

沙箱工具限制输出大小以保持 Agent 上下文可控。这些限制可配置：

sandbox:
  use: FacetX.sandbox.local:LocalSandboxProvider
 
  # bash 使用中间截断（头部 + 尾部）
  bash_output_max_chars: 20000
 
  # read_file 使用头部截断
  read_file_output_max_chars: 50000
 
  # ls 使用头部截断
  ls_output_max_chars: 20000

设置为 0 禁用截断。

安全性

LocalSandbox

LocalSandbox 直接在主机上运行命令。默认情况下，bash 工具被禁用以防止任意主机命令执行。仅对完全受信任的单用户工作流启用它：

sandbox:
  allow_host_bash: true # 危险：授予 Agent 对你机器的 Shell 访问权限

即使没有 bash，Agent 也可以通过专用文件工具读写文件。

容器沙箱

基于容器的沙箱提供文件系统和进程隔离。Agent 看不到或修改主机文件系统，除非通过显式挂载。Provisioner 管理模式增加了额外一层：每个线程获得自己的隔离 Pod。

审计中间件

SandboxAuditMiddleware 在每次 Agent 轮次上运行，记录所有沙箱操作，提供会话期间访问了哪些文件、运行了哪些命令的审计跟踪。

工具子 Agent
简介