5.18日
不只是“调用 API 传入命令”，但最表层看起来确实像这样：
const sandbox = await Sandbox.create()
const result = await sandbox.commands.run("npm test")
这只是 Agent 和沙箱交互的“控制面”。真正复杂的是：沙箱怎么被创建、文件怎么进去、依赖怎么准备、运行状态怎么保持、结果怎么同步回来。
1. 沙箱本质是什么？
像 E2B、CubeSandbox 这类东西，可以理解成：
给 Agent 临时分配一台隔离的远程 Linux 小电脑，让它在里面读写文件、安装依赖、执行命令、跑浏览器、跑测试、访问网络。
E2B 官方描述里，sandbox 可以访问 Linux OS、创建/删除文件、运行命令、执行代码和访问互联网。(e2b.dev)
CubeSandbox 则更偏自部署/高隔离方向，它提供 E2B 兼容 API，理论上可以把 E2B Cloud 切到 CubeSandbox，只改环境变量或 endpoint。(GitHub)
所以从 Agent 角度看，它确实像：
create sandbox
upload / sync files
run command
read stdout / stderr
read changed files
destroy / pause sandbox
但从平台角度看，它更像一个远程开发容器 / MicroVM 编排系统。
2. 怎么保持和本地一致的文件？
通常有几种方式。
方式一：启动时上传项目文件
最直接：
本地项目目录
↓ 打包 / 遍历
上传到 sandbox 的 /home/user/project
↓
agent 在里面 npm install / pnpm test / 修改文件
↓
把修改后的文件下载回来
适合小项目、一次性任务。
缺点是：项目大时上传慢，node_modules、.git、dist 这种目录要排除，不然你传一次，咖啡都凉了。
方式二：Git Clone
如果项目在 GitHub/GitLab 上，可以让沙箱直接：
git clone <repo>
cd project
pnpm install
这也是很多 coding agent 的常见方式。
优点是干净、可复现。
缺点是：本地未提交的改动不会自动存在。要么先生成 patch，要么上传当前 workspace diff。
常见流程是：
clone repo
apply local patch
run tests
agent modifies files
generate diff
apply diff back to local
这其实很像远程 CI + 自动补丁系统。
方式三：文件系统同步 / Watcher
更高级的做法是：
本地 watch 文件变化
↓
实时同步到 sandbox
↓
sandbox 修改文件后
↓
同步回本地
E2B 的 SDK 文档里也有文件系统相关能力，比如文件操作、watch filesystem events 这类机制。(e2b.dev)
这种模式更接近“远程开发环境”，适合长时间交互式 Agent。
但它要处理很多坑：
冲突：本地和远程同时改了同一个文件怎么办？
忽略规则：node_modules、dist、.git、coverage 要不要同步？
权限：chmod、软链接、隐藏文件怎么处理？
大小文件：图片、视频、模型文件要不要传？
一致性：远程执行命令时，文件是否已经同步完成？
所以成熟的 Agent 平台通常不会简单粗暴同步全部文件，而是做增量、过滤、diff 或版本快照。
方式四：挂载外部持久化存储
有些场景会把数据挂到沙箱里，比如：
/mnt/data
/mnt/workspace
/mnt/cache
这样 sandbox 销毁后，关键数据还能保留。E2B 相关生态里也能看到把持久化存储挂载后，在 sandbox 中用普通文件系统命令读写的例子。(DeepLake Docs)
这种方式适合：
用户上传的数据集
构建缓存
模型文件
运行结果
长期项目文件
3. 怎么保持环境一致？
文件一致只是第一步，更难的是环境一致。
比如你本地是：
Node.js 20.11
pnpm 9
Ubuntu 22.04
Chrome 版本 X
Python 3.11
特定环境变量
特定系统依赖
沙箱如果不一致，Agent 跑出来的问题可能是假的。
常见解决方案有这些。
4. 用镜像 / Template 保持基础环境一致
E2B 有 template 机制，可以定义 sandbox 的基础镜像、环境变量、要复制的文件、构建命令和启动命令。它甚至可以在构建 template 时预先运行命令并做快照，这样创建 sandbox 时已经是配置好的状态。(e2b.dev)
可以理解成 Dockerfile + 预热快照：
base image: node:20 / python:3.11 / ubuntu
install: pnpm, git, playwright, chromium
copy: package.json, lockfile
run: pnpm install
snapshot
之后每个 Agent 启动时不是从零安装，而是从这个快照克隆。
这解决的是：
不用每次 npm install
不用每次 apt install
统一 Node / Python / 系统依赖版本
加快启动速度
CubeSandbox 也强调资源池、快照克隆、MicroVM 隔离等机制，目标就是让每个 Agent 有独立环境，同时启动足够快。(GitHub)
5. 用 lockfile 保持依赖一致
前端项目最关键的是：
package.json
pnpm-lock.yaml / yarn.lock / package-lock.json
.npmrc
Agent 进入沙箱后一般会执行：
corepack enable
pnpm install --frozen-lockfile
这样它安装的依赖版本才和你本地接近。
但要注意：lockfile 只能锁 JS 包版本，锁不了系统环境。
比如这些仍然可能不一致：
Node 版本
操作系统
glibc 版本
浏览器版本
canvas/sharp/esbuild 等原生依赖
环境变量
CPU 架构
所以更稳的是配合：
.nvmrc
.node-version
Dockerfile
devcontainer.json
CI 配置
6. 用 devcontainer / Dockerfile 对齐本地和沙箱
如果你项目里有：
.devcontainer/devcontainer.json
Dockerfile
docker-compose.yml
Agent 平台可以按这个环境启动。
理想状态是：
本地 VS Code Dev Container
CI 环境
Agent Sandbox
线上构建环境
都用同一套镜像。
这样 Agent 的结果更可信。
比如：
FROM node:20-bullseye
RUN corepack enable
RUN apt-get update && apt-get install -y git python3 make g++
WORKDIR /workspace
然后 sandbox 创建时基于这个镜像。
这就是为什么很多团队会把“Agent 可执行环境”当成工程基础设施，而不是随便给它一个 Ubuntu。
7. 环境变量和密钥怎么处理？
沙箱里还要注入：
OPENAI_API_KEY
GITHUB_TOKEN
DATABASE_URL
VITE_API_BASE_URL
NPM_TOKEN
E2B 文档里也有环境变量相关能力。(e2b.dev)
但这里要非常小心：Agent 运行的是模型生成的命令，不能随便把生产密钥丢进去。
更安全的做法是：
只给最小权限 token
使用临时 token
区分读权限和写权限
禁止访问生产数据库
网络访问做白名单
敏感文件不上传
否则 Agent 一句 cat .env，安全部门的血压就开始响应式更新了。
8. Agent 修改后的文件怎么回到本地？
通常不是“远程改完就直接覆盖本地”，而是生成 diff。
流程大概是：
1. 上传或 clone 项目
2. Agent 修改文件
3. git diff 生成补丁
4. 返回给用户审查
5. 用户确认后应用到本地 / 创建 PR
比如：
git diff
然后平台把 diff 拿回来：
- old code
+ new code
再让用户确认。
像 Codex、Claude Code、Cursor 这类工具的工作流，本质上很多也是围绕：
读文件 → 改文件 → 跑命令 → 生成 diff → 用户确认
只是有的是本地执行，有的是远程沙箱执行。
9. 沙箱的状态能保持多久？
取决于平台设计。一般有几种状态：
临时 sandbox：任务结束就销毁
会话 sandbox：一次对话期间保持
持久 workspace：文件/缓存长期保存
template snapshot：环境长期保存，但每次任务从快照克隆
E2B、CubeSandbox 这类通常会强调快速创建隔离环境。CubeSandbox 文档里提到 MicroVM、资源池、快照克隆等，说明它不是简单开一个 Docker 容器，而是在隔离和启动速度之间做了工程优化。(GitHub)
实际开发中，你会把状态分成三类：
代码文件：需要持久化
依赖缓存：最好持久化，提高速度
运行临时状态：可以丢弃
10. 和本地一致的关键不是“同步全部”，而是“可复现”
很多人第一反应是：
那我把本地所有文件同步过去，不就一致了吗？
不完全对。
真正可靠的是：
代码版本一致
依赖版本一致
系统版本一致
环境变量一致
启动命令一致
测试命令一致
权限和网络边界一致
也就是“可复现环境”。
所以比较成熟的方案是：
Git commit / patch
+ lockfile
+ Dockerfile / template
+ env schema
+ sandbox startup script
+ test command
而不是单纯 scp -r ./project sandbox:/workspace。
11. 一个比较真实的 Agent 沙箱流程
以前端项目为例，完整流程可能是这样：
用户：帮我修复 infinite scroll 的 bug
Agent 平台：
1. 创建 sandbox
2. 基于 node20-vue-template 启动
3. clone repo
4. apply 当前本地 diff
5. pnpm install --frozen-lockfile
6. 读取相关文件
7. 修改组件代码
8. pnpm test / pnpm lint / pnpm build
9. 如果失败，继续修
10. 生成 git diff
11. 返回修改说明和 diff
12. 用户确认后应用到本地或创建 PR
13. 销毁 sandbox
你看到的 API 可能只是：
sandbox.commands.run("pnpm test")
sandbox.files.write("/workspace/src/App.vue", content)
sandbox.files.read("/workspace/src/App.vue")
但背后有一整套工作区同步和环境准备。
12. E2B 和 CubeSandbox 的定位区别
简单说：
E2B：
偏托管云服务 + SDK 生态成熟
适合快速接入 Agent，让它安全执行代码
CubeSandbox：
偏开源、自部署、高隔离、高并发
兼容 E2B API，适合想把 Agent 沙箱放到自己基础设施里的团队
CubeSandbox 文档中明确提到它有 E2B-compatible REST API gateway，可以较低成本从 E2B Cloud 切换过来。(GitHub)
这意味着上层 Agent 代码可能基本不变：
const sandbox = await Sandbox.create()
await sandbox.commands.run("npm test")
但底层从 E2B 的云环境换成你自己部署的 CubeSandbox 集群。
13. 你可以这样理解三层架构
第一层：Agent 决策层
LLM 决定要读哪个文件、跑什么命令、怎么改代码
第二层：Sandbox API 层
create sandbox / run command / read file / write file / upload / download
第三层：执行环境层
Docker / MicroVM / Firecracker / KVM / containerd / snapshot / network policy
E2B、CubeSandbox 主要解决第二层和第三层。
而 Codex、Claude Code、OpenClaw、各种浏览器 Agent，则主要在第一层和第二层之间做集成。
14. 最终回答你的问题
是的，表层上就是调用 API，把命令传进去执行。
但真正的 Agent 沙箱不只是：
API + command
而是：
API + 文件同步 + 镜像模板 + 依赖缓存 + 环境变量 + 权限隔离 + 状态管理 + diff 回传
“和本地一致”通常靠这些东西组合实现：
1. Git clone / 文件上传 / patch 同步
2. lockfile 保证依赖版本
3. Dockerfile / template / devcontainer 保证系统环境
4. env 注入保证运行配置
5. 持久化 volume / cache 保证缓存和数据
6. git diff / 文件下载把结果同步回来
最推荐的工程化做法是：
不要追求把本地机器完整复制过去；
而是把项目变成一个任何干净环境都能复现的 workspace。
也就是：
git clone
pnpm install --frozen-lockfile
pnpm test
pnpm build
能稳定跑通。
这一步做好之后，Agent 沙箱就不是“玄学远程电脑”，而是一个可控、可复现、可销毁的自动打工人环境。