沙箱管理套件:让 AI Agent 拥有可观测的代码执行环境

一套「Agent 干活,人类围观」的完整沙箱生态 —— SDK 负责创建和操作,Console 负责观察和管理,两者通过共享历史数据库无缝协作。 配套组件开源地址: agent-sandbox-backends:https://gitee.com/rainbow-zhou/agent-sandbox-backend.git sandbox-web:https://gitee.com/rainbow-zhou/sandbox-web.git

为什么需要它?

当 AI Agent(如 Deep Agents)开始在沙箱里写代码、跑命令、改文件时,一个关键问题浮现:人类怎么知道 Agent 到底做了什么?

传统方案要么让 Agent 自说自话(黑盒),要么让人手动翻日志(痛苦)。更棘手的是,如果出了问题——文件被覆盖了、命令跑飞了、沙箱挂了——你连现场都看不到。

OpenSandbox 沙箱管理套件 正是为解决这个问题而生:

• agent-sandbox-backends —— 给 Agent 用的 SDK,一条命令创建沙箱、执行操作、自动记录完整历史

• sandbox-console —— 给人用的 Web 控制台,浏览器里查看文件、执行命令、回溯操作历史

两者不直接通信,而是通过沙箱内的共享 SQLite 历史数据库协作。Agent 写入操作记录,Console 同步并展示,形成统一的时间线。

它能做什么?

Console 的五大核心功能

SDK 的核心能力

• 沙箱生命周期:创建、连接、暂停、恢复、删除、TTL 自动续期

• 文件操作:读写、编辑(乐观并发 CAS)、删除、批量上传(安全扫描 + Manifest 校验)

• 命令执行:流式输出、超时控制、取消、输出截断保护

• 操作历史:自动记录每个操作的 STARTED → OUTPUT → TERMINAL 全生命周期

• 并发控制:文件 KeyedRWLock、命令队列限流、生命周期互斥

• Deep Agents 集成:一条命令适配为 Deep Agents Backend 协议

三分钟快速上手

第一步:安装 agent-sandbox-backends和sandbox-web

pip install sandbox-console agent-sandbox-backends

前端已预编译并打包进 wheel,无需 Node.js。启动:

sandbox-console-server                     # 默认 http://localhost:9090
sandbox-console-server –port 3000         # 自定义端口

Console 默认端口 9090,避开 OpenSandbox Service 的 8080。本地使用无需任何环境变量,鉴权默认关闭。

第二步:注册连接

打开浏览器访问 http://localhost:9090,进入 Connections 页面:

第三步:创建沙箱(可以创建,也可以不创建,sdk端会自动创建一个新的)

在 Sandboxes 页面点击「Create Sandbox」,选择镜像(默认 python:3.12),设置工作目录,即可创建。

第四步:给 Agent 用

from agent_sandbox_backends.integrations.deepagents import as_deepagents_backend
import asyncio
import os
​
from deepagents import create_deep_agent
​
from dotenv import load_dotenv
from agent_sandbox_backends import create_opensandbox_backend
from langchain.chat_models import init_chat_model
from langgraph.checkpoint.memory import InMemorySaver
​
load_dotenv(override=True)
API_KEY = os.getenv("API_KEY")
BASE_URL = os.getenv("BASE_URL")
model = init_chat_model(
  model="deepseek-v4-flash",
  api_key=API_KEY,
  base_url=BASE_URL
)
async def create():
  backend = await create_opensandbox_backend(
      "http://localhost:9090", # 沙箱服务的地址和端口号
      sandbox_name="research-workspace", # 沙箱的名称
  )
  # 创建沙箱
  deepagents_backend = as_deepagents_backend(backend)
  return create_deep_agent(
      model=model,
      backend=deepagents_backend
  )
agent = asyncio.run(create())

第五步:回到 Console 观察

现在回到浏览器,进入沙箱详情页:

点击Open进入沙箱内部,会看到以下几个标签

• Files Tab

  • 用于查看文件树

• Commands Tab

  • 用于执行命令

• History Tab

  • 用于查看沙箱的操作历史:如创建沙箱和创建文件,执行命令等操作历史

关键体验:Agent 和你的操作在历史时间线里统一排序展示,你能清楚看到「Agent 先写了文件 → 你手动跑了个命令 → Agent 又改了文件」的完整过程。

快速体验

1. 通过Agent创建文件夹和文件,同时写入内容

1.1 查看操作历史

注: 操作历史加载可能会慢一点,如果发现没有历史,可以稍等一下刷新一下即可

2. 对文件内容进行更改

2.1 查看操作历史

3. 执行命令

3.1 查看操作历史

4. 上传文件操作

5. web端更改文件内容

5.1 查看操作历史

6. web端执行命令

6.1 查看操作历史

其他设计

1. 历史不丢:Dual Cursor 机制

Console 同步历史时使用双游标确保数据不丢:

acknowledged_seq ← 已确认 ACK 的位置
pending_seq       ← 已写入本地但未 ACK 的位置

流程:拉取变更 → 写入本地 Projection + pending_seq → 提交事务 → ACK → 提升为 acknowledged。ACK 失败?下次重试,pending_seq 保留,数据不丢。

2. 历史不重:幂等 Upsert

每条历史事件有 event_id(UUIDv7)和 source_seq(单调递增)。同步时按 event_id 去重,source_seq 更高才更新,天然幂等。

3. 历史完整:Console 操作也回写

Console 自己执行的操作(命令、文件编辑)不仅记录在本地 console_activities 表,还通过 SandboxHistoryStore.append() 回写到沙箱的 Canonical History,确保 Agent 和 Console 的操作在同一个数据库里统一管理。

4. 并发安全:SDK 层的精细化锁

5. 上传安全:防 zip-slip 等

SDK 的上传管线包含:路径规范化 → 允许根目录校验 → 敏感文件排除(.env/.ssh/.aws/.git)→ SHA-256 Manifest → Staging 安全解压(防绝对路径/../symlink/device)→ 校验 → 原子提交或回滚。

6. Provider Key 对齐

Console 的 Adapter 内部强制使用 provider_key="opensandbox-default" 传给 SDK(而非用 connection.id),因为 SDK 在初始化沙箱历史时用这个 key 做身份校验。不匹配会报 History identity conflict,导致 Console 无法读写历史。

适用场景

• AI 代码助手开发:给 Agent 一个安全沙箱跑代码,你实时观察

• 自动化研究流水线:Agent 在沙箱里装包、跑实验,你在 Console 审计每一步

• 教学与演示:学生看 Agent 操作沙箱的过程,理解 AI 编程的工作方式

• 多 Agent 协作调试:多个 Agent 共享一个沙箱,通过历史时间线排查冲突

• 安全审计:所有操作有据可查,命令、文件变更、stdout/stderr 全留存

总结

一句话:Agent 用 SDK 在沙箱里干活并自动记录历史,你用 Console 在浏览器里看历史、查文件、跑命令。两者通过沙箱内的共享 SQLite 协作,无需 Agent 关心 Console 是否在线,也无需 Console 关心 Agent 是谁。