OpenSandbox 本地快速上手Docker 运行时、多语言 SDK 与 CLI 的最短路径【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 是一个面向 AI 应用的通用沙箱平台提供统一的生命周期 API、多语言 SDK 和 Docker/Kubernetes 双运行时。本文基于官方 Quick Start 文档docs/getting-started/index.md完整展开从生成 Docker 运行时的服务端配置、启动生命周期服务器到用 Python SDK 创建并操作第一个沙箱执行命令、读写文件、运行代码解释器最后用osbCLI 完成同样的操作并深入仓库源码说明每一步背后的实现。一、快速上手整体流程Quick Start 的完整路径只有四步启动 Serveruvx opensandbox-server拉起生命周期 API 服务默认监听127.0.0.1:8080安装 SDKPython / JavaScript / Go / C# / Kotlin-Java 任选创建并使用沙箱SDK 中Sandbox.create(...)一步完成容器拉起随后调用commands、files、Code Interpreter 等能力CLI 替代路径osb命令行完成创建与命令执行。前提条件PrerequisitesDockerEngine 20.10本地执行沙箱所依赖的运行时Python3.10服务端与 Python SDK 均要求uv推荐或 pip。Python 3.10 的要求在 Python SDK 的包定义中有明确声明sdks/sandbox/python/pyproject.toml 中requires-python 3.10且兼容到 3.13。二、启动生命周期 Server2.1 生成初始配置# Generate a starter config uvx opensandbox-server init-config ~/.sandbox.toml --example docker # Start the server uvx opensandbox-serverinit-config并不是简单的模板复制命令。从 server/opensandbox_server/cli.py 可以看到它支持四种打包示例--example {docker, docker-zh, k8s, k8s-zh}分别对应包内的example.config.toml、example.config.zh.toml、example.config.k8s.toml、example.config.k8s.zh.toml四份模板如果不带--example则会调用render_full_config()基于 Pydantic 配置模型渲染一份全字段占位骨架注释直接来自 schema 的Fielddescription保证与校验逻辑同步。目标文件已存在时需要--force才会覆盖否则会报FileExistsError。服务端配置的默认路径是~/.sandbox.toml可用环境变量SANDBOX_CONFIG_PATH覆盖或使用opensandbox-server --config /path/to/sandbox.toml为当前进程显式指定——这三者优先级关系在 server/configuration.md 开头有完整说明。2.2 验证服务健康curl http://127.0.0.1:8080/health # → {status: healthy}/health是服务端 FastAPI 应用注册的公共端点见 server/opensandbox_server/main.py。从鉴权中间件的源码结构看/health、/version、/docs、/redoc、/openapi.json均属于免 API Key 路径server/opensandbox_server/middleware/auth.py因此即使配置了server.api_key健康检查也不需要携带凭证。2.3 启动过程的源码视角uvx opensandbox-server执行的入口是 server/opensandbox_server/cli.py 中的main()若传入--config会将其写入SANDBOX_CONFIG_PATH环境变量随后load_config()解析 TOML、configure_logging()初始化日志最终由 uvicorn 加载opensandbox_server.main:app监听地址与端口来自[server]配置默认0.0.0.0:8080并透传timeout_keep_alive、limit_concurrency、backlog、loop、http等 uvicorn 参数。源码注释里有一个值得注意的设计启动阶段刻意只加载配置与日志延迟导入main模块——因为导入opensandbox_server.main会立即构造sandbox_service恢复容器、启动过期定时器把这些副作用推迟到真正的 worker 进程可避免--reload模式下 uvicorn 的 reloader 监督进程重复执行恢复逻辑。三、Docker 运行时示例配置解读init-config --example docker落盘的模板就是仓库中的 server/opensandbox_server/examples/example.config.toml。与快速上手相关的核心项配置段关键项示例值说明[server]host/port127.0.0.1/8080HTTP API 绑定地址max_sandbox_timeout_seconds 86400限制沙箱 TTL 上限[server]api_key注释项空未设置时启动需显式确认风险交互式 TTY 输入YES或非交互环境设置OPENSANDBOX_INSECURE_SERVERYES[runtime]type/execd_imagedocker/opensandbox/execd:v1.1.0必填段execd 镜像负责在沙箱内引导命令/文件访问通道[docker]network_modebridge本地执行建议 bridgeegress 出站策略强制要求 bridge[docker]port_range_min/port_range_max40000/60000bridge 模式下沙箱端口分配区间每个沙箱需 2–3 个宿主机端口区间需 ≥100 个端口[docker]drop_capabilities/no_new_privileges/pids_limit见模板默认丢弃危险 capability、禁止提权、限制 PID 数4096[egress]image/modeopensandbox/egress:v1.1.7/dns出站策略 sidecar仅在创建请求携带networkPolicy时挂载[store]type/pathsqlite/~/.opensandbox/opensandbox.db服务端持久化元数据快照等默认用 SQLite无需外部数据库[ingress]modedirectDocker 运行时下 ingress 只允许direct模式跨字段校验规则完整的字段参考包括[kubernetes]、[secure_runtime]、[renew_intent]、[otel]等本地快速用不到的段见 server/configuration.md。需要特别注意一条跨字段校验runtime.type docker时不得出现[kubernetes]或[agent_sandbox]段且ingress.mode必须为direct——校验逻辑在opensandbox_server/config.py的AppConfig.validate_runtime_blocks中。四、安装 SDKQuick Start 支持的语言与安装命令语言安装命令仓库对应源码Pythonpip install opensandboxsdks/sandbox/pythonJavaScriptnpm install alibaba-group/opensandboxsdks/sandbox/javascriptGogo get github.com/alibaba/OpenSandbox/sdks/sandbox/gosdks/sandbox/goC#dotnet add package Alibaba.OpenSandboxsdks/sandbox/csharpKotlin/Java见 安装文档sdks/sandbox/kotlinPython SDK 的运行时依赖收敛在pydantic、httpx、httpx-sse等少数几个库上见 sdks/sandbox/python/pyproject.toml异步优先、通过 SSE 接收执行事件流。五、创建并使用第一个沙箱Python 完整示例以下是 Quick Start 文档中的完整示例可直接复制运行需要能访问opensandbox/code-interpreter镜像import asyncio from datetime import timedelta from code_interpreter import CodeInterpreter, SupportedLanguage from opensandbox import Sandbox from opensandbox.models import WriteEntry async def main() - None: # Create a sandbox with code interpreter sandbox await Sandbox.create( opensandbox/code-interpreter:v1.1.0, entrypoint[/opt/code-interpreter/code-interpreter.sh], env{PYTHON_VERSION: 3.11}, timeouttimedelta(minutes10), ) async with sandbox: # Execute a shell command execution await sandbox.commands.run(echo Hello OpenSandbox!) print(execution.logs.stdout[0].text) # Write and read a file await sandbox.files.write_files([ WriteEntry(path/tmp/hello.txt, dataHello World, mode644) ]) content await sandbox.files.read_file(/tmp/hello.txt) print(fContent: {content}) # Run code via the Code Interpreter interpreter await CodeInterpreter.create(sandbox) result await interpreter.codes.run( import sys; print(sys.version); 2 2, languageSupportedLanguage.PYTHON, ) print(result.result[0].text) # 4 await sandbox.kill() if __name__ __main__: asyncio.run(main())示例中每一步对应的底层能力Sandbox.create(image, entrypoint, env, timeout)向生命周期服务发起创建请求。从 SDK 服务层协议 sdks/sandbox/python/src/opensandbox/services/sandbox.py 可以看到create_sandbox的完整参数面除spec镜像、entrypoint、env、timeout外还支持resource资源限制、network_policy出站策略、volumes卷挂载、extensions透传扩展参数、snapshot_id从快照恢复等。timeout为沙箱 TTL到期自动回收传None则创建需显式清理的长生命周期沙箱。async with sandbox保证上下文退出时的资源清理。sandbox.commands.run(...)命令执行经沙箱内的 execd 通道下发返回的execution.logs.stdout是分段的日志列表示例取第一段文本Hello OpenSandbox!。sandbox.files.write_files / read_file文件系统操作以WriteEntry(path, data, mode)批量写入随后read_file读回校验。Code InterpreterCodeInterpreter.create(sandbox)在已有沙箱上构建代码执行句柄codes.run(code, language...)通过 execd 的code_interpretingAPI 运行代码并返回结果段示例中2 2的结果是4。注意Code Interpreter SDK 需单独安装pip install opensandbox-code-interpreteropensandbox/code-interpreter容器镜像由 opensandbox-group/sandbox-images 仓库维护见原文档提示。六、用 CLI 完成同样操作不想写代码时osb命令行可以直接驱动同一套 APIpip install opensandbox-cli osb config init osb config set connection.domain localhost:8080 osb config set connection.protocol http osb sandbox create --image python:3.12 --timeout 30m -o json osb command run sandbox-id -o raw -- python -c print(1 1)流程说明osb config init生成 CLI 本地配置config set写入连接目标localhost:8080http协议即指向第二节启动的 Serverosb sandbox create --image python:3.12 --timeout 30m -o json以python:3.12镜像创建沙箱并设置 30 分钟 TTL-o json输出结构化结果从中取回 sandbox-idosb command run sandbox-id -o raw -- python -c print(1 1)在沙箱内执行任意命令--之后的部分原样作为要执行的命令。CLI 的完整命令集、输出格式json/raw等与配置项可在仓库的 cli/README.md 与 docs/cli/index.md 中查阅其源码位于 cli/src/opensandbox_cli。七、验证、限制与下一步验证要点curl http://127.0.0.1:8080/health返回{status: healthy}即表示生命周期 API 就绪此后 SDK/CLI 的所有操作都经由该端口进入 Server再由 Server 调度 Docker 运行时拉起沙箱容器。适用前提与限制本地快速上手默认 Docker 运行时需要本机 Docker Engine 20.10Kubernetes 运行时的完整部署另见 docs/kubernetes/index.md 与 kubernetes/README.mdserver.api_key未设置时服务可匿名访问启动时要求显式确认YES或OPENSANDBOX_INSECURE_SERVERYES——本地开发可行公网暴露务必配置 API Key对应请求头OPEN-SANDBOX-API-KEY沙箱创建请求的timeout受server.max_sandbox_timeout_seconds上限约束示例配置为 86400 秒bridge 网络模式下端口分配依赖port_range_min/max并发沙箱规模要与该区间匹配。下一步原文档 Next Steps路径已转换为仓库内相对路径安装指南 — 各 SDK 与运行时的详细安装配置参考 — 服务端配置完整说明架构文档 — OpenSandbox 内部工作机制功能指南 — Credential Vault、安全容器等进阶特性示例合集 — 真实场景用法生命周期 API 的公开契约定义见 specs/sandbox-lifecycle.yml是服务端与所有 SDK 共同的接口依据。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考