尧图网页设计 
OpenSandbox 接入 AIO Sandbox 实战从服务器启动到沙箱健康检查的完整流程【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于 OpenSandbox 仓库中的 AIOAll-in-OneSandbox 示例文档讲解如何启动 OpenSandbox Server 并创建、访问一个 AIO 沙箱实例。读完本文你可以独立完成 Docker 运行时下的服务器部署、通过 OpenSandbox Python SDK 创建带自定义健康检查的沙箱、再使用 agent-sandbox SDK 在其中执行 Shell 命令、读取文件和抓取浏览器截图的完整实战流程。AIO Sandbox 是什么一个镜像承载 Shell、文件与浏览器能力AIO Sandbox 是 agent-infra/sandbox 项目提供的 All-in-One 沙箱镜像ghcr.io/agent-infra/sandbox:latest。它将 Shell 执行、文件操作、浏览器控制等能力打包进同一个容器由镜像内的统一入口进程示例中使用/opt/gem/run.sh对外暴露一套 HTTP API如/v1/shell/sessions。OpenSandbox 在其中承担“控制平面”的角色AIO 镜像本身只负责“提供能力”而沙箱的创建、生命周期、端口映射、健康探测、超时回收都由 OpenSandbox Server 负责。示例代码 examples/aio-sandbox/main.py 演示的正是这两者的分工通过 OpenSandbox SDKopensandbox.SandboxSync向服务器申请一个运行 AIO 镜像的容器并等待它就绪拿到服务器分配/代理的接入点后切换为 AIO 官方 SDKagent_sandbox.Sandbox直接调用容器内的 Shell、文件、浏览器 API。仓库内该示例的完整文档为 docs/examples/aio-sandbox.md示例目录说明见 examples/aio-sandbox/README.md。前置条件Docker 运行时与 AIO 镜像OpenSandbox Server 默认配置为 Docker 运行时runtime.type docker因此宿主机必须存在一个正在运行的 Docker daemon服务器才能与之通信Docker Desktop确认 Docker Desktop 已启动并用docker version验证ColimamacOS先执行colima start并在启动服务器前导出 socket 地址export DOCKER_HOSTunix://${HOME}/.colima/default/docker.sock建议预先拉取示例使用的 AIO 镜像避免首次创建沙箱时因拉取镜像而显著变慢# pre-pull target image docker pull ghcr.io/agent-infra/sandbox:latest如果后续在日志中看到来自docker/transport/unixconn.py的FileNotFoundError: [Errno 2] No such file or directory错误通常意味着 Docker unix socket 不存在或 Docker daemon 未运行应优先检查上面的运行时前置条件。启动 OpenSandbox Server安装服务器命令行工具然后用打包内置的 Docker 示例配置生成配置文件并启动服务uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server从 server/opensandbox_server/cli.py 中的实现可以看出init-config子命令支持四种打包示例docker、docker-zh、k8s、k8s-zh由--example参数选择不带该参数时会渲染一个完整但带占位符的配置骨架。docker示例即仓库中维护的 server/opensandbox_server/examples/example.config.toml。理解这份配置有助于排查示例运行问题关键段落包括[server] host 127.0.0.1 port 8080 max_sandbox_timeout_seconds 86400 [runtime] type docker execd_image opensandbox/execd:v1.1.0 [store] type sqlite path ~/.opensandbox/opensandbox.db [docker] network_mode bridge port_range_min 40000 port_range_max 60000 pids_limit 4096 no_new_privileges true几个与 AIO 示例直接相关的要点[server] port 8080决定了后续示例代码里http://localhost:8080这个服务器地址的来源max_sandbox_timeout_seconds是单个沙箱寿命上限示例中 300s 的 timeout 必须落在该上限内[docker] port_range_min/max定义了 bridge 模式下为沙箱分配宿主机端口的区间。注释说明每个沙箱需要 2~3 个宿主机端口带 egress sidecar 时为 3 个因此示例输出中形如127.0.0.1:56123的接入点端口就来自该区间[store] type sqlite说明默认使用本地 SQLite 持久化沙箱元数据单机快速上手无需额外数据库配置文件中api_key默认为空。若保持为空服务器启动时需要显式确认非安全模式交互终端输入YES非交互场景设置OPENSANDBOX_INSECURE_SERVERYES生产环境应填入api_key。注意opensandbox-server以前台方式运行并占用当前终端。由于示例代码位于本仓库中需要克隆仓库后新开一个终端cd到项目根目录再执行下面的 AIO 沙箱创建步骤。示例代码解析创建 AIO 沙箱并访问其能力示例采用一组固定配置以便快速上手OpenSandbox 服务器http://localhost:8080镜像ghcr.io/agent-infra/sandbox:latestAIO 端口8080超时300s在仓库根目录安装依赖并运行uv pip install opensandbox agent-sandbox0.0.18 uv run python examples/aio-sandbox/main.py自定义健康检查轮询 /v1/shell/sessionsAIO 容器的入口进程启动需要时间因此示例没有依赖默认就绪逻辑而是传入一个自定义健康检查函数def check_aio_process(sbx: SandboxSync) - bool: Health check: poll aio process at /v1/shell/sessions until it returns 200. try: endpoint sbx.get_endpoint(8080) start time.perf_counter() url fhttp://{endpoint.endpoint}/v1/shell/sessions for _ in range(150): # max for ~30s try: resp requests.get(url, timeout1) if resp.status_code 200: elapsed time.perf_counter() - start print(f[check] sandbox ready after {elapsed:.1f}s) return True except Exception as exc: pass time.sleep(0.2) return False except Exception as exc: print(f[check] failed: {exc}) return False该函数的策略是先向 OpenSandbox 服务器查询 8080 端口的接入点然后以约 0.2s 间隔最多轮询 150 次约 30 秒直到 AIO 的/v1/shell/sessions接口返回 200。从 SDK 源码结构看这个函数会被接入 sdks/sandbox/python/src/opensandbox/sync/sandbox.py 中SandboxSync.create的就绪等待流程create在创建成功后未显式skip_health_check时调用check_ready(ready_timeout, health_check_polling_interval)轮询的超时预算与间隔控制实现在 sdks/sandbox/python/src/opensandbox/internal/readiness.py 的ReadinessBudget.health_sync中超时未就绪会抛出SandboxReadyTimeoutException。这就是示例默认ready_timeout30s与上面 150 次轮询上限相匹配的原因。创建沙箱SandboxSync.create 的关键参数sandbox SandboxSync.create( imageimage, # AIO 镜像 timeouttimedelta(secondstimeout_seconds), # 沙箱寿命 300s metadata{example: aio-sandbox}, # 自定义元数据 entrypoint[/opt/gem/run.sh], # 覆盖容器入口启动 AIO 服务 connection_configConnectionConfigSync(domainserver), health_checkcheck_aio_process, # 自定义就绪判定 )结合SandboxSync.create的实现见 sdks/sandbox/python/src/opensandbox/sync/sandbox.py#L454-L595有几个对实操很有用的默认值与行为entrypoint若不提供默认为[tail, -f, /dev/null]。AIO 示例显式传入[/opt/gem/run.sh]以容器内 AIO 的统一服务入口替代默认保活命令——这正是沙箱能对外提供 Shell/文件/浏览器 API 的前提resource未显式指定时默认为{cpu: 1, memory: 2Gi}timeout默认 10 分钟传None则要求显式清理。示例传入 300s沙箱在运行到期后被服务器回收失败自愈若创建过程在初始化阶段抛出异常SDK 会尝试kill_sandbox终止这个“僵尸沙箱”源码中Attempting to terminate zombie sandbox分支避免在服务器上残留无主容器。访问沙箱Shell、文件与浏览器沙箱就绪后with sandbox:上下文管理器保证结束时清理本地资源核心交互流程为with sandbox: endpoint sandbox.get_endpoint(8080) # 通过服务器解析 AIO 接入点 print(fAIO portal endpoint: {endpoint.endpoint}) client AioSandboxClient(base_urlfhttp://{endpoint.endpoint}) home_dir client.sandbox.get_context().home_dir # 1) Shell在沙箱内执行命令 result client.shell.exec_command(commandls -la, timeout10) print(result.data.output) # 2) 文件读取容器内文件内容 content client.file.read_file(filef{home_dir}/.bashrc) print(content.data.content) # 3) 浏览器流式下载截图到本地 screenshot_path sandbox_screenshot.png with open(screenshot_path, wb) as f: for chunk in client.browser.screenshot(): f.write(chunk) print(fScreenshot saved to {screenshot_path}) # 4) 显式终止远程沙箱 sandbox.kill()从 sdks/sandbox/python/src/opensandbox/sync/sandbox.py 的源码可以确认两个容易混淆的语义get_endpoint(port)会向服务器查询该沙箱在指定端口上的接入点SandboxEndpoint示例输出的AIO portal endpoint: 127.0.0.1:56123即服务器在 bridge 端口区间内映射出的宿主机地址服务器侧默认proxy.resolve_internal true时反向代理实际指向沙箱容器的 Docker bridge IP见 server/opensandbox_server/examples/example.config.toml 中[proxy]段注释kill()只向远程沙箱发送终止信号不会关闭本地 HTTP 客户端等资源本地资源由上下文管理器退出时的close()负责。两者分工明确源码注释中也特别提示了这一区别。运行输出成功运行后终端会依次显示创建沙箱、健康检查通过、接入点信息、ls -la与.bashrc的输出以及最终截图保存结果Creating AIO sandbox with imageghcr.io/agent-infra/sandbox:latest on OpenSandbox server http://localhost:8080... [check] sandbox ready after 7.1s AIO portal endpoint: 127.0.0.1:56123 ... Screenshot saved to sandbox_screenshot.png下图即为示例脚本在沙箱内通过 AIO 浏览器能力抓取并下载回本地的浏览器页面截图故障排查要点结合文档与源码常见的几类问题可以快速定位现象原因与排查FileNotFoundError来自docker/transport/unixconn.pyDocker unix socket 缺失或 daemon 未运行检查docker version或 Colima 的DOCKER_HOST导出服务器启动即提示非安全确认未配置api_key按提示输入YES或设置OPENSANDBOX_INSECURE_SERVERYES生产环境请配置api_key沙箱就绪超时AIO 入口进程 30 秒内未返回 200确认镜像是否已预拉取、entrypoint是否为[/opt/gem/run.sh]并可适当调大ready_timeout接入点端口落在 40000~60000 之外检查[docker] port_range_min/port_range_max配置并确认宿主机防火墙放行该区间创建中途失败但服务器残留容器SDK 在异常分支会尝试 kill 僵尸沙箱若仍残留可在服务器上按metadata如exampleaio-sandbox定位清理参考与延伸阅读示例文档docs/examples/aio-sandbox.md示例代码examples/aio-sandbox/main.py服务器 Docker 示例配置server/opensandbox_server/examples/example.config.toml配置生成命令实现server/opensandbox_server/cli.py同步 SDK 沙箱创建与健康检查sdks/sandbox/python/src/opensandbox/sync/sandbox.py、sdks/sandbox/python/src/opensandbox/internal/readiness.pyAIO Sandbox 项目及其 Python SDK 的更多用法可参考 agent-infra/sandbox 仓库的官方 examples仓库中的同类接入示例还可对照 docs/examples/code-interpreter.md 与 docs/examples/chrome.md 理解不同能力镜像的复用模式。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenSandbox 接入 AIO Sandbox 实战：从服务器启动到沙箱健康检查的完整流程
OpenSandbox 接入 AIO Sandbox 实战从服务器启动到沙箱健康检查的完整流程【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于 OpenSandbox 仓库中的 AIOAll-in-OneSandbox 示例文档讲解如何启动 OpenSandbox Server 并创建、访问一个 AIO 沙箱实例。读完本文你可以独立完成 Docker 运行时下的服务器部署、通过 OpenSandbox Python SDK 创建带自定义健康检查的沙箱、再使用 agent-sandbox SDK 在其中执行 Shell 命令、读取文件和抓取浏览器截图的完整实战流程。AIO Sandbox 是什么一个镜像承载 Shell、文件与浏览器能力AIO Sandbox 是 agent-infra/sandbox 项目提供的 All-in-One 沙箱镜像ghcr.io/agent-infra/sandbox:latest。它将 Shell 执行、文件操作、浏览器控制等能力打包进同一个容器由镜像内的统一入口进程示例中使用/opt/gem/run.sh对外暴露一套 HTTP API如/v1/shell/sessions。OpenSandbox 在其中承担“控制平面”的角色AIO 镜像本身只负责“提供能力”而沙箱的创建、生命周期、端口映射、健康探测、超时回收都由 OpenSandbox Server 负责。示例代码 examples/aio-sandbox/main.py 演示的正是这两者的分工通过 OpenSandbox SDKopensandbox.SandboxSync向服务器申请一个运行 AIO 镜像的容器并等待它就绪拿到服务器分配/代理的接入点后切换为 AIO 官方 SDKagent_sandbox.Sandbox直接调用容器内的 Shell、文件、浏览器 API。仓库内该示例的完整文档为 docs/examples/aio-sandbox.md示例目录说明见 examples/aio-sandbox/README.md。前置条件Docker 运行时与 AIO 镜像OpenSandbox Server 默认配置为 Docker 运行时runtime.type docker因此宿主机必须存在一个正在运行的 Docker daemon服务器才能与之通信Docker Desktop确认 Docker Desktop 已启动并用docker version验证ColimamacOS先执行colima start并在启动服务器前导出 socket 地址export DOCKER_HOSTunix://${HOME}/.colima/default/docker.sock建议预先拉取示例使用的 AIO 镜像避免首次创建沙箱时因拉取镜像而显著变慢# pre-pull target image docker pull ghcr.io/agent-infra/sandbox:latest如果后续在日志中看到来自docker/transport/unixconn.py的FileNotFoundError: [Errno 2] No such file or directory错误通常意味着 Docker unix socket 不存在或 Docker daemon 未运行应优先检查上面的运行时前置条件。启动 OpenSandbox Server安装服务器命令行工具然后用打包内置的 Docker 示例配置生成配置文件并启动服务uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server从 server/opensandbox_server/cli.py 中的实现可以看出init-config子命令支持四种打包示例docker、docker-zh、k8s、k8s-zh由--example参数选择不带该参数时会渲染一个完整但带占位符的配置骨架。docker示例即仓库中维护的 server/opensandbox_server/examples/example.config.toml。理解这份配置有助于排查示例运行问题关键段落包括[server] host 127.0.0.1 port 8080 max_sandbox_timeout_seconds 86400 [runtime] type docker execd_image opensandbox/execd:v1.1.0 [store] type sqlite path ~/.opensandbox/opensandbox.db [docker] network_mode bridge port_range_min 40000 port_range_max 60000 pids_limit 4096 no_new_privileges true几个与 AIO 示例直接相关的要点[server] port 8080决定了后续示例代码里http://localhost:8080这个服务器地址的来源max_sandbox_timeout_seconds是单个沙箱寿命上限示例中 300s 的 timeout 必须落在该上限内[docker] port_range_min/max定义了 bridge 模式下为沙箱分配宿主机端口的区间。注释说明每个沙箱需要 2~3 个宿主机端口带 egress sidecar 时为 3 个因此示例输出中形如127.0.0.1:56123的接入点端口就来自该区间[store] type sqlite说明默认使用本地 SQLite 持久化沙箱元数据单机快速上手无需额外数据库配置文件中api_key默认为空。若保持为空服务器启动时需要显式确认非安全模式交互终端输入YES非交互场景设置OPENSANDBOX_INSECURE_SERVERYES生产环境应填入api_key。注意opensandbox-server以前台方式运行并占用当前终端。由于示例代码位于本仓库中需要克隆仓库后新开一个终端cd到项目根目录再执行下面的 AIO 沙箱创建步骤。示例代码解析创建 AIO 沙箱并访问其能力示例采用一组固定配置以便快速上手OpenSandbox 服务器http://localhost:8080镜像ghcr.io/agent-infra/sandbox:latestAIO 端口8080超时300s在仓库根目录安装依赖并运行uv pip install opensandbox agent-sandbox0.0.18 uv run python examples/aio-sandbox/main.py自定义健康检查轮询 /v1/shell/sessionsAIO 容器的入口进程启动需要时间因此示例没有依赖默认就绪逻辑而是传入一个自定义健康检查函数def check_aio_process(sbx: SandboxSync) - bool: Health check: poll aio process at /v1/shell/sessions until it returns 200. try: endpoint sbx.get_endpoint(8080) start time.perf_counter() url fhttp://{endpoint.endpoint}/v1/shell/sessions for _ in range(150): # max for ~30s try: resp requests.get(url, timeout1) if resp.status_code 200: elapsed time.perf_counter() - start print(f[check] sandbox ready after {elapsed:.1f}s) return True except Exception as exc: pass time.sleep(0.2) return False except Exception as exc: print(f[check] failed: {exc}) return False该函数的策略是先向 OpenSandbox 服务器查询 8080 端口的接入点然后以约 0.2s 间隔最多轮询 150 次约 30 秒直到 AIO 的/v1/shell/sessions接口返回 200。从 SDK 源码结构看这个函数会被接入 sdks/sandbox/python/src/opensandbox/sync/sandbox.py 中SandboxSync.create的就绪等待流程create在创建成功后未显式skip_health_check时调用check_ready(ready_timeout, health_check_polling_interval)轮询的超时预算与间隔控制实现在 sdks/sandbox/python/src/opensandbox/internal/readiness.py 的ReadinessBudget.health_sync中超时未就绪会抛出SandboxReadyTimeoutException。这就是示例默认ready_timeout30s与上面 150 次轮询上限相匹配的原因。创建沙箱SandboxSync.create 的关键参数sandbox SandboxSync.create( imageimage, # AIO 镜像 timeouttimedelta(secondstimeout_seconds), # 沙箱寿命 300s metadata{example: aio-sandbox}, # 自定义元数据 entrypoint[/opt/gem/run.sh], # 覆盖容器入口启动 AIO 服务 connection_configConnectionConfigSync(domainserver), health_checkcheck_aio_process, # 自定义就绪判定 )结合SandboxSync.create的实现见 sdks/sandbox/python/src/opensandbox/sync/sandbox.py#L454-L595有几个对实操很有用的默认值与行为entrypoint若不提供默认为[tail, -f, /dev/null]。AIO 示例显式传入[/opt/gem/run.sh]以容器内 AIO 的统一服务入口替代默认保活命令——这正是沙箱能对外提供 Shell/文件/浏览器 API 的前提resource未显式指定时默认为{cpu: 1, memory: 2Gi}timeout默认 10 分钟传None则要求显式清理。示例传入 300s沙箱在运行到期后被服务器回收失败自愈若创建过程在初始化阶段抛出异常SDK 会尝试kill_sandbox终止这个“僵尸沙箱”源码中Attempting to terminate zombie sandbox分支避免在服务器上残留无主容器。访问沙箱Shell、文件与浏览器沙箱就绪后with sandbox:上下文管理器保证结束时清理本地资源核心交互流程为with sandbox: endpoint sandbox.get_endpoint(8080) # 通过服务器解析 AIO 接入点 print(fAIO portal endpoint: {endpoint.endpoint}) client AioSandboxClient(base_urlfhttp://{endpoint.endpoint}) home_dir client.sandbox.get_context().home_dir # 1) Shell在沙箱内执行命令 result client.shell.exec_command(commandls -la, timeout10) print(result.data.output) # 2) 文件读取容器内文件内容 content client.file.read_file(filef{home_dir}/.bashrc) print(content.data.content) # 3) 浏览器流式下载截图到本地 screenshot_path sandbox_screenshot.png with open(screenshot_path, wb) as f: for chunk in client.browser.screenshot(): f.write(chunk) print(fScreenshot saved to {screenshot_path}) # 4) 显式终止远程沙箱 sandbox.kill()从 sdks/sandbox/python/src/opensandbox/sync/sandbox.py 的源码可以确认两个容易混淆的语义get_endpoint(port)会向服务器查询该沙箱在指定端口上的接入点SandboxEndpoint示例输出的AIO portal endpoint: 127.0.0.1:56123即服务器在 bridge 端口区间内映射出的宿主机地址服务器侧默认proxy.resolve_internal true时反向代理实际指向沙箱容器的 Docker bridge IP见 server/opensandbox_server/examples/example.config.toml 中[proxy]段注释kill()只向远程沙箱发送终止信号不会关闭本地 HTTP 客户端等资源本地资源由上下文管理器退出时的close()负责。两者分工明确源码注释中也特别提示了这一区别。运行输出成功运行后终端会依次显示创建沙箱、健康检查通过、接入点信息、ls -la与.bashrc的输出以及最终截图保存结果Creating AIO sandbox with imageghcr.io/agent-infra/sandbox:latest on OpenSandbox server http://localhost:8080... [check] sandbox ready after 7.1s AIO portal endpoint: 127.0.0.1:56123 ... Screenshot saved to sandbox_screenshot.png下图即为示例脚本在沙箱内通过 AIO 浏览器能力抓取并下载回本地的浏览器页面截图故障排查要点结合文档与源码常见的几类问题可以快速定位现象原因与排查FileNotFoundError来自docker/transport/unixconn.pyDocker unix socket 缺失或 daemon 未运行检查docker version或 Colima 的DOCKER_HOST导出服务器启动即提示非安全确认未配置api_key按提示输入YES或设置OPENSANDBOX_INSECURE_SERVERYES生产环境请配置api_key沙箱就绪超时AIO 入口进程 30 秒内未返回 200确认镜像是否已预拉取、entrypoint是否为[/opt/gem/run.sh]并可适当调大ready_timeout接入点端口落在 40000~60000 之外检查[docker] port_range_min/port_range_max配置并确认宿主机防火墙放行该区间创建中途失败但服务器残留容器SDK 在异常分支会尝试 kill 僵尸沙箱若仍残留可在服务器上按metadata如exampleaio-sandbox定位清理参考与延伸阅读示例文档docs/examples/aio-sandbox.md示例代码examples/aio-sandbox/main.py服务器 Docker 示例配置server/opensandbox_server/examples/example.config.toml配置生成命令实现server/opensandbox_server/cli.py同步 SDK 沙箱创建与健康检查sdks/sandbox/python/src/opensandbox/sync/sandbox.py、sdks/sandbox/python/src/opensandbox/internal/readiness.pyAIO Sandbox 项目及其 Python SDK 的更多用法可参考 agent-infra/sandbox 仓库的官方 examples仓库中的同类接入示例还可对照 docs/examples/code-interpreter.md 与 docs/examples/chrome.md 理解不同能力镜像的复用模式。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考