OpenSandbox 实战指南：在 AI Agent 沙箱中启动 code-server 实现浏览器端 VS Code 访问

OpenSandbox 实战指南：在 AI Agent 沙箱中启动 code-server 实现浏览器端 VS Code 访问

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

本文基于 OpenSandbox 官方示例文档docs/examples/vscode.md编写，讲解如何在 OpenSandbox 中构建并运行一个预装 code-server（VS Code Web）的沙箱镜像，通过几行 Python SDK 代码把一套完整的浏览器端 IDE 能力注入 AI Agent 的执行环境。读完本文，你将掌握：VS Code 沙箱镜像的构建方式、本地 OpenSandbox server 的启动流程、main.py示例脚本中各环境变量的含义，以及Sandbox.create、commands.run、get_endpoint三个核心 SDK API 的底层实现链路，最终得到一个可以通过浏览器直接访问的沙箱内 VS Code 实例。

示例定位：为什么要在沙箱里跑 VS Code

OpenSandbox 是一个面向 AI Agent 的运行时沙箱系统。Agent 在执行代码、操作文件、调试程序时往往需要一个完整的开发环境。examples/vscode示例给出的方案是：在沙箱容器内运行 code-server（VS Code 的官方 Web 版本），通过 OpenSandbox 的端口端点机制对外暴露 HTTP 服务，使用户无需在本机安装任何 VS Code 组件，直接用浏览器即可获得一个隔离在沙箱内的工作区 IDE。

这一方案的价值在于：Agent 与开发者共享同一个隔离环境，且该环境的文件系统、网络出口都被 OpenSandbox 管控，IDE 本身也成为 Agent 可操控的对象。

构建 VS Code 沙箱镜像

示例目录examples/vscode下提供了完整的 Dockerfile，构建命令为：

cd examples/vscode docker build -t opensandbox/vscode:latest .

从 Dockerfile 源码看，镜像的构建逻辑分为四层关键步骤：

1. 基础镜像：基于debian:12-slim，并通过一条apt-get语句一次性安装python3、python3-pip、curl、ca-certificates，随后清理 apt 缓存以控制层体积；
2. 安装 code-server：直接调用官方安装脚本curl -fsSL https://code-server.dev/install.sh | sh，这是 code-server 官方推荐的安装方式；
3. 非 root 用户：创建系统组与用户vscode，并建立/home/vscode与工作目录/workspace，两者均chown给该用户——这是官方文档强调的“Non-root user for security”设计；
4. 运行身份与工作区：WORKDIR /workspace指定容器工作目录，USER vscode切换为非特权用户，默认命令为bash。

官方文档说明该镜像包含三个特性：预装 code-server、非 root 用户vscode、工作区目录/workspace。构建完成后镜像标签为opensandbox/vscode:latest。

启动本地 OpenSandbox Server

示例文档给出的是本地（Docker 运行时）部署路径。首先需要预拉取官方构建好的 VS Code 镜像（避免首次创建沙箱时现拉镜像）：

docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/vscode:latest

随后通过 uv 安装 server 端并生成示例配置：

uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server

三条命令分别完成：安装服务端包、以 docker 运行时模板生成~/.sandbox.toml配置文件、启动 OpenSandbox server（默认监听localhost:8080，与示例脚本的默认值一致）。配置文件本身的完整参数说明可参考 server/configuration.md。

运行 main.py：创建并访问 VS Code 沙箱

在安装了 SDK 的环境（仓库根目录即可，示例目录为examples/vscode）中执行：

# Install OpenSandbox package uv pip install opensandbox uv run python examples/vscode/main.py

可配置环境变量

阅读 main.py 源码，脚本支持以下环境变量覆盖默认值：

脚本执行流程逐段解读

main.py的核心逻辑按顺序分为四步：

1. 建立连接配置并创建沙箱

config = ConnectionConfig( domain=domain, api_key=api_key, request_timeout=timedelta(seconds=60), ) sandbox = await Sandbox.create( image, connection_config=config, env=env, # 注入 {"PYTHON_VERSION": "3.11"} )

Sandbox.create是异步工厂方法，向 server 发起创建请求，env参数把PYTHON_VERSION注入到容器环境。ConnectionConfig中的request_timeout设为 60 秒，覆盖创建、执行命令等所有 HTTP 请求的超时。

2. 后台启动 code-server

start_exec = await sandbox.commands.run( f"code-server --bind-addr 0.0.0.0:{code_port} --auth none /workspace", opts=RunCommandOpts(background=True), )

命令含义：code-server 绑定0.0.0.0:8443，--auth none关闭认证（因为访问控制由 OpenSandbox 的端点机制承担），打开/workspace作为根工作区。关键在RunCommandOpts(background=True)——命令以 detached 方式运行，commands.run不会阻塞等待 code-server 进程退出（它本来就不会退出），而是立即返回执行句柄，脚本随后用_print_logs打印启动日志的 stdout/stderr。

3. 获取可访问的端点

endpoint = await sandbox.get_endpoint(code_port) print(f" http://{endpoint.endpoint}/")

这是整个示例最核心的一步：不直接暴露容器端口，而是通过 OpenSandbox 的 endpoint 机制拿到对外访问地址。从 Python SDK 源码看，Sandbox.get_endpoint 会把请求委托给沙箱服务层，最终调用 SandboxesAdapter.get_sandbox_endpoint，后者请求 server 的get_sandboxes_sandbox_id_endpoints_port接口，并带有一个use_server_proxy开关——当连接配置启用了 server 代理时，端点地址会指向 server 侧的代理入口而非容器网络直连地址。Adapter 层还内置了按(sandbox_id, port, use_server_proxy)三元组缓存端点的逻辑，重复调用不会反复打到 server。

4. 保活与清理

await asyncio.sleep(600) # 沙箱保活 10 分钟 finally: await sandbox.kill()

脚本在async with sandbox:上下文中休眠 10 分钟让浏览器访问窗口保持打开，期间用户可直接在浏览器使用 IDE；Ctrl+C或到期后在finally中调用sandbox.kill()销毁沙箱，确保不会泄漏容器资源。

端点机制小结：安全边界在哪

示例中 code-server 特意使用--auth none，看似不安全，实际上访问控制被上移到了 OpenSandbox 的端点层：客户端必须先持有对 server 的有效连接（API Key、域名），才能通过get_endpoint(port)换取特定端口的访问地址；在 server 代理模式下，流量还要经过 server 侧转发。此外，沙箱内进程以非 root 用户vscode运行，工作区被限定在/workspace。这两层（非特权容器身份 + 端点代理）共同构成了浏览器 IDE 场景下的隔离边界。

延伸参考

• 完整的沙箱创建、命令执行、端口暴露 API 详见 docs/sdks/python.md；
• 端点安全访问（含签名端点get_signed_endpoint）的机制设计见 OSEP-0011 Secure Access Endpoint 与 docs/guides/secure-access.md；
• 其他浏览器内 GUI 场景（noVNC 桌面）可对照 examples/desktop/README.md 中的 noVNC 方案，理解 OpenSandbox 端口端点机制在图形化负载上的通用性。

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox