从零开始部署阿里巴巴开源的 AI 沙箱平台，解决 AI Agent 代码执行的安全隐患
OpenSandbox 是阿里巴巴开源的 AI 应用通用沙箱平台，专门用于安全、隔离地运行 AI 代理生成的代码、自动化脚本以及桌面应用交互。
无论是本地开发还是生产部署，OpenSandbox 都提供了标准化的解决方案。该项目的诞生，正是为了解决 AI 代理在自主执行代码时带来的安全与运维挑战。
本指南将带你快速上手 OpenSandbox，从零开始在本地部署并运行一个沙箱实例。
OpenSandbox 是一个专为 AI 应用设计的通用沙箱平台，它提供了一个安全、隔离的环境，用于执行 AI 生成的代码。你可以把它想象成一个 "数字隔离病房" ——AI 可以在里面写代码、跑脚本、操作文件，但所有操作都被隔离在一个安全的容器里，完全不会影响到宿主系统。
项目的核心价值在于，它提供了标准化的安全环境，让开发者无需从头构建复杂的防御体系，即可将本地原型无缝迁移至生产级的分布式部署架构中。
随着 AI Agent 技术的快速发展，越来越多的应用需要让 AI 自主执行代码。但这种能力也带来了严重的安全和运维挑战：
在实际项目中，我们发现很多 AI Agent 框架没有内置沙箱机制，这带来了严重的安全风险：
常见问题：
rm -rf 命令）后果：
想象一下，你让 AI Agent 帮你处理一个数据分析任务，但它执行的代码不小心删除了你的项目文件夹，或者泄露了你的 API 密钥。这种风险在生产环境中是不可接受的。
OpenSandbox 正是为了解决这类问题而生的：
效果：
即使 AI 生成了恶意代码或执行了危险操作，也只会影响沙箱容器本身，不会对宿主机造成任何损害。沙箱销毁后，一切恢复原状。
| 特性 | 传统 AI Agent（无沙箱） | OpenSandbox（有沙箱） |
|---|---|---|
| 代码执行环境 | 宿主机直接执行 | Docker 容器隔离执行 |
| 文件系统安全 | ❌ 可访问和修改宿主机文件 | ✅ 仅访问沙箱内文件 |
| 数据泄露风险 | ❌ 可读取环境变量、密钥 | ✅ 隔离的环境变量 |
| 资源控制 | ❌ 无法限制 CPU/内存 | ✅ 内置超时和资源限制 |
| 错误影响范围 | ❌ 可能影响整个系统 | ✅ 仅影响沙箱容器 |
| 生产环境适用性 | ❌ 不推荐 | ✅ 生产级安全标准 |
除了安全性，OpenSandbox 还提供了以下价值：
OpenSandbox 的核心理念是：让 AI 自由发挥，但限制在安全边界内。
开始前，请确保你的本地环境满足以下要求：
首先，在终端中安装 opensandbox-server 包，并生成一个针对 Docker 运行时的示例配置文件。
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
使用以下命令启动服务器。默认情况下，服务会运行在 localhost:8080。
opensandbox-server
查看启动时终端的输出日志，确认服务已成功运行。
打开一个新的终端窗口，安装 OpenSandbox 的 Python SDK 和代码解释器扩展包：
uv pip install opensandbox-code-interpreter
重要：预拉取 Docker 镜像
在运行演示脚本之前，必须先预拉取所需的 Docker 镜像。如果直接运行 opensandbox_demo.py，可能会因为首次拉取镜像超时而失败。
# 使用国内镜像源预拉取（推荐）
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2
# 验证镜像是否成功拉取
docker images | grep code-interpreter
这一步非常重要，因为：
现在，通过一个完整的 Python 脚本来验证所有组件是否正常工作。
import asyncio
import httpx
from datetime import timedelta
from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models import WriteEntry
async def main() -> None:
# 配置连接(设置更长的超时时间)
config = ConnectionConfig(
domain="http://localhost:8080", # Docker Desktop 默认地址
use_server_proxy=False, # 尝试禁用 server proxy 模式
request_timeout=timedelta(seconds=120), # 增加请求超时到 120 秒
transport=httpx.AsyncHTTPTransport(
limits=httpx.Limits(max_connections=20)
),
)
print("正在创建沙箱...")
print(f"配置: {config}")
# 1. Create a sandbox
sandbox = await Sandbox.create(
# 使用阿里云镜像源(国内网络更快)
"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",
# "opensandbox/code-interpreter:v1.0.2", # 原 Docker Hub 镜像
entrypoint=["/opt/opensandbox/code-interpreter.sh"],
env={"PYTHON_VERSION": "3.11"},
timeout=timedelta(hours=2), # 空闲超时:2小时(不使用时自动清理)
connection_config=config, # 添加连接配置
ready_timeout=timedelta(seconds=120), # 增加健康检查超时到 120 秒
health_check_polling_interval=timedelta(seconds=5), # 每 5 秒检查一次
)
print(f"✓ 沙箱创建成功! ID: {sandbox.id}")
print(f"\n提示：现在容器正在运行，你可以打开 Docker Desktop 查看")
print(f"按 Enter 键继续执行并清理沙箱...")
input()
async with sandbox:
# 2. Execute a shell command
execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
print(execution.logs.stdout[0].text)
# 3. Write a file
await sandbox.files.write_files([
WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
])
# 4. Read a file
content = await sandbox.files.read_file("/tmp/hello.txt")
print(f"Content: {content}") # Content: Hello World
# 5. Create a code interpreter
interpreter = await CodeInterpreter.create(sandbox)
# 6. 执行 Python 代码（单次执行：直接传 language）
result = await interpreter.codes.run(
"""
import sys
print(sys.version)
result = 2 + 2
result
""",
language=SupportedLanguage.PYTHON,
)
print(result.result[0].text) # 4
print(result.logs.stdout[0].text) # 3.11.14
# 7. Cleanup the sandbox
await sandbox.kill()
if __name__ == "__main__":
asyncio.run(main())
将以上脚本保存为 demo.py，确保 opensandbox-server 正在运行，然后在终端执行 python demo.py。
如果一切顺利，你将看到类似下面的输出：
至此，你已经成功运行了自己的第一个 OpenSandbox 沙箱！
📜 总结
OpenSandbox 通过标准化的 API,将复杂的容器管理、安全隔离和资源调度等基础设施细节进行了封装,为解决 AI 应用的安全执行难题提供了生产级的解决方案。本文带你从零开始,在本地通过 Docker 完成了 OpenSandbox 的部署和基本使用。未来,你还可以基于此扩展到更复杂的场景,如 GUI 自动化、强化学习训练等。
根据实际使用经验，以下是遇到的一些常见问题及其解决方案：
现象：执行 Sandbox.create() 时出现 httpx.ReadTimeout 错误
原因：
解决方案：
from opensandbox.config import ConnectionConfig
from datetime import timedelta
import httpx
# 显式配置连接参数,增加超时时间
config = ConnectionConfig(
domain="http://localhost:8080",
use_server_proxy=False, # 禁用server proxy模式
request_timeout=timedelta(seconds=120), # 设置为120秒
transport=httpx.AsyncHTTPTransport(
limits=httpx.Limits(max_connections=20)
),
)
sandbox = await Sandbox.create(
"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2", # 使用阿里云镜像
entrypoint=["/opt/opensandbox/code-interpreter.sh"],
env={"PYTHON_VERSION": "3.11"},
timeout=timedelta(hours=2),
connection_config=config,
ready_timeout=timedelta(seconds=120),
health_check_polling_interval=timedelta(seconds=5),
)
注意：不要尝试在 AsyncHTTPTransport 中设置 timeout 参数，该参数不被支持。
现象：Sandbox health check timed out after 120.0s，提示 server proxy mode enabled
原因：客户端配置 use_server_proxy=True 启用了服务端代理模式，但本地运行的 Server 未正确支持该模式
解决方案：确保 ConnectionConfig 中 use_server_proxy=False，使客户端直连沙箱容器
现象：SDK 请求 /api/sandboxes 返回 404，而实际有效路径是 /v1/sandboxes
原因：SDK 默认请求路径与 Server 实际暴露路径不一致
解决方案：
现象：直接执行 opensandbox_demo.py 时报错 httpx.ReadTimeout
原因分析：
解决方案：
在首次运行演示脚本之前，务必先手动拉取镜像：
# 使用国内镜像源预拉取
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2
# 验证镜像是否存在
docker images | grep code-interpreter
完整的运行流程：
# 1. 启动 OpenSandbox Server
opensandbox-server
# 2. 在新终端中预拉取镜像
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2
# 3. 等待镜像拉取完成后，运行演示脚本
python opensandbox_demo.py
注意：如果已经成功拉取过镜像，后续运行可以直接执行演示脚本，无需重复拉取。
推荐的 ConnectionConfig 配置：
from opensandbox.config import ConnectionConfig
from datetime import timedelta
import httpx
config = ConnectionConfig(
domain="http://localhost:8080", # 本地Server地址
use_server_proxy=False, # 禁用server proxy模式
request_timeout=timedelta(seconds=120), # 增加请求超时时间
transport=httpx.AsyncHTTPTransport(
limits=httpx.Limits(max_connections=20)
),
)
sandbox = await Sandbox.create(
"sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2",
connection_config=config,
ready_timeout=timedelta(seconds=120),
health_check_polling_interval=timedelta(seconds=5),
timeout=timedelta(hours=2),
)
避免的配置：
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。