尧图网页设计 
在 OpenSandbox 中运行 Nullclaw Gateway从服务端启动、HTTP 端点暴露到出口网络策略的完整实战【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于仓库内的官方示例文档 docs/examples/nullclaw.md 与配套脚本 examples/nullclaw/main.py 编写讲解如何在 OpenSandbox 沙箱中拉起 Nullclaw Gateway 容器、通过 Python SDK 轮询其/health健康检查直至就绪、获取宿主侧可达的 HTTP 端点并配合出口egress网络策略将网关的外网访问收敛到单一目标域名。读完后你可以独立复现该示例并理解 SDK 创建沙箱、端点解析与网络策略下发背后的关键实现。这个示例解决什么问题Nullclaw 是一个极简的 AI 助手运行时官方文档将其描述为 678 KB 静态 Zig 二进制。OpenSandbox 将其作为任意 HTTP 服务托管进沙箱由 OpenSandbox server 负责拉起容器并管理生命周期SDK 负责在本地完成创建、健康检查与端口映射解析最终把网关服务暴露为宿主可达的127.0.0.1:端口形式。示例的自动化闭环是向 OpenSandbox server 请求创建一个以 Nullclaw 镜像为启动源、存活时间 1 小时的沙箱通过沙箱的 3000 端口端点轮询http://endpoint/health直到返回 HTTP 200就绪后打印最终可达的 Gateway 地址例如127.0.0.1:56234。这一模式并不局限于 Nullclaw——任何容器内跑 HTTP 服务 端口暴露的场景Webhook 网关、开发服务器、代理等都可以复用同样的 SDK 调用链。环境准备启动 OpenSandbox serverDocker 运行时前提OpenSandbox server 默认使用runtime.type docker因此必须能连上一个正在运行的 Docker daemonDocker Desktop保持其运行并用docker version验证ColimamacOS先启动colima start再导出 socketexport DOCKER_HOSTunix://${HOME}/.colima/default/docker.sock预拉取镜像并启动 serverNullclaw 容器镜像发布在 GHCR 上预拉取可显著缩短首次创建沙箱的时间docker pull ghcr.io/nullclaw/nullclaw:latest安装并启动 OpenSandbox server日志会留在终端中uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server其中init-config生成的~/.sandbox.toml采用 docker 运行时配置模板server 默认监听localhost:8080与后文脚本中硬编码的服务地址一致。创建并访问 Nullclaw 沙箱参数约定该示例为快速上手做了硬编码见 main.py参数值说明OpenSandbox serverhttp://localhost:8080管理 API 地址镜像ghcr.io/nullclaw/nullclaw:latestNullclaw Gateway 容器Gateway 端口3000容器内监听端口用于get_endpoint与/health轮询超时3600s沙箱最大存活时间到期后自动回收安装依赖并运行从项目根目录安装 Python SDK 与requests健康检查轮询使用uv pip install opensandbox requests运行示例uv run python examples/nullclaw/main.py成功时的输出形如Creating nullclaw sandbox with imageghcr.io/nullclaw/nullclaw:latest on OpenSandbox server http://localhost:8080... [check] sandbox ready after 0.3s Nullclaw gateway started. Please refer to 127.0.0.1:56234最后一行打印的端点例如127.0.0.1:56234就是 OpenSandbox 从沙箱映射出来的 Nullclaw Gateway 地址可直接用curl访问其公开端点curl http://127.0.0.1:56234/health关于认证端点Nullclaw 默认要求先完成 pairing配对之后才能使用带认证的端点例如/webhook/health端点始终保持公开可访问——这也是本示例选它作为就绪判据的原因。脚本逐段解析对照源码健康检查函数check_nullclawcheck_nullclaw 是传给 SDK 的自定义同步健康检查返回True表示就绪False表示超时或异常def check_nullclaw(sbx: SandboxSync) - bool: try: endpoint sbx.get_endpoint(3000) start time.perf_counter() url fhttp://{endpoint.endpoint}/health 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: pass time.sleep(0.2) return False except Exception as exc: print(f[check] failed: {exc}) return False要点sbx.get_endpoint(3000)通过管理 API 解析 3000 端口在宿主侧的可达地址对应 SDK 中 SandboxSync.get_endpoint 的实现——它调用sandbox_service.get_sandbox_endpoint(self.id, port, use_server_proxy)把容器端口翻译为宿主可直连的endpoint字符串本地 docker 运行时下即127.0.0.1:映射端口轮询策略为单次请求 1 秒超时、间隔 0.2 秒、最多 150 次总等待上限约 30 秒任何网络异常都被吞掉继续轮询适合容器已启动但进程尚未 listen的窗口期。从 SDK 源码结构看SandboxSync.create收到health_check参数后会把它保存为custom_health_check并在 check_ready 流程中按health_check_polling_interval默认 200ms反复调用直到返回True或超过ready_timeout默认 30 秒。因此本例实际上有双层 30 秒预算内层是check_nullclaw自身的 150 次轮询外层是 SDK 的ready_timeout。创建沙箱的完整调用main 函数 中的一次性创建调用覆盖了 SDK 的关键能力面sandbox SandboxSync.create( imageimage, timeouttimedelta(secondstimeout_seconds), metadata{example: nullclaw}, connection_configConnectionConfigSync(domainserver), health_checkcheck_nullclaw, # use network policy to limit nullclaw network accesses network_policyNetworkPolicy( defaultActiondeny, egress[NetworkRule(actionallow, targetopenrouter.ai)], ), ) endpoint sandbox.get_endpoint(3000) print(fNullclaw gateway started. Please refer to {endpoint.endpoint})对照 SandboxSync.create 签名各参数语义如下image容器镜像引用字符串会被包装为SandboxImageSpec与snapshot_id二选一源码中有显式校验timeout3600s沙箱最大存活时间对应示例文档中Timeout: 3600s到期自动回收若传None则表示需要显式清理metadata自定义元数据这里打了一个example: nullclaw标记便于后续按元数据过滤沙箱列表connection_config指向本地 server 的同步连接配置health_check即上文轮询函数SDK 阻塞等待其通过后才返回network_policy出口网络策略下一节展开。另外可以注意 SDK 的默认行为未显式传resource时默认为{cpu: 1, memory: 2Gi}见 create 实现中的默认值未传entrypoint时默认[tail, -f, /dev/null——而 Nullclaw 镜像自带入口进程所以示例无需覆盖。ConnectionConfigSyncSDK 如何连到 serverConnectionConfigSync 是所有同步 SDK HTTP 客户端共享的连接配置本例只显式设置了domainhttp://localhost:8080其余走默认值字段默认值作用domainlocalhost:8080或OPEN_SANDBOX_DOMAIN环境变量管理 API 基地址自动拼接/v1protocolhttp仅接受http/httpsrequest_timeout30s管理 API 请求超时api_key环境变量OPEN_SANDBOX_API_KEY服务端开启鉴权时使用use_server_proxyFalse为True时让 server 代理 execd 请求适用于客户端无法直连沙箱端点的部署形态若未传入transportSDK 会为每个实例自建带重试与 deadline 控制的共享 transportwith_transport_if_missing见 连接配置实现这也是 SDK 具备弹性传输重试、超时收敛能力的基础。出口网络策略默认拒绝仅放行 openrouter.ai示例中最值得展开的一行是创建沙箱时附带的network_policynetwork_policyNetworkPolicy( defaultActiondeny, egress[NetworkRule(actionallow, targetopenrouter.ai)], )对照 SDK 模型定义 NetworkPolicy 与 NetworkRuledefault_action别名defaultAction未匹配任何规则时的默认动作默认即为deny即未列出的一律拒绝egress规则列表按顺序求值每条NetworkRule由actionallow/deny与targetFQDN 或通配域名如*.example.com组成target为空会直接校验失败。也就是说这个 Nullclaw 沙箱在数据面只被允许出站到openrouter.aiNullclaw 调用大模型 API 的目标域名其余所有外网访问都会被拦截。NetworkPolicy的模型注释明确指出它与 egress sidecar 的/policy请求体保持一致——从源码结构看策略由 OpenSandbox 的 egress 组件独立组件目录 components/egress在沙箱网络边界执行这正是 OpenSandboxFQDN 粒度出口管控能力在示例中的直接应用。这条策略体现了沙箱的典型安全姿态入向端口由 OpenSandbox 受控映射只有显式get_endpoint(3000)才暴露 3000 端口出向流量默认全断、白名单放行。对于承载 LLM 网关这类只需要打一个上游 API的负载这种最小化出口面几乎零成本。端到端流程小结把示例各角色串起来一次uv run python examples/nullclaw/main.py的完整链路是SDK 经ConnectionConfigSync(domainhttp://localhost:8080)调 server 管理 API携带镜像、1 小时超时、metadata 与deny-by-default出口策略创建沙箱server 通过 Docker 运行时拉起ghcr.io/nullclaw/nullclaw:latest容器首次前需docker pull预拉取并为 execd / egress / 业务端口建立可解析的端点SDK 用自定义health_check轮询get_endpoint(3000)映射出的http://host/health200 即就绪就绪后再次get_endpoint(3000)打印最终 Gateway 地址后续即可对该地址调用/health公开或完成 pairing 后的认证端点如/webhook。延伸阅读仓库内路径示例脚本与本地 READMEexamples/nullclaw/main.py、examples/nullclaw/README.mdPython SDK 沙箱创建与端点解析sdks/sandbox/python/src/opensandbox/sync/sandbox.pycreate见 L454 起get_endpoint见 L223 起同步连接配置sdks/sandbox/python/src/opensandbox/config/connection_sync.py网络策略模型sdks/sandbox/python/src/opensandbox/models/sandboxes.pyL117-L152egress 组件实现与文档components/egress/README.md、docs/components/egress.md服务端本地部署与配置server/README.md、server/configuration.md复现前提本机可运行的 Docker daemon、Python 3 环境与uv且 server 与示例脚本在同一台机器localhost:8080直连形态。若你的部署形态是 K8s 或其他运行时init-config与网络策略的落地方式会有差异应以 server 配置文档为准。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 OpenSandbox 中运行 Nullclaw Gateway：从服务端启动、HTTP 端点暴露到出口网络策略的完整实战
在 OpenSandbox 中运行 Nullclaw Gateway从服务端启动、HTTP 端点暴露到出口网络策略的完整实战【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于仓库内的官方示例文档 docs/examples/nullclaw.md 与配套脚本 examples/nullclaw/main.py 编写讲解如何在 OpenSandbox 沙箱中拉起 Nullclaw Gateway 容器、通过 Python SDK 轮询其/health健康检查直至就绪、获取宿主侧可达的 HTTP 端点并配合出口egress网络策略将网关的外网访问收敛到单一目标域名。读完后你可以独立复现该示例并理解 SDK 创建沙箱、端点解析与网络策略下发背后的关键实现。这个示例解决什么问题Nullclaw 是一个极简的 AI 助手运行时官方文档将其描述为 678 KB 静态 Zig 二进制。OpenSandbox 将其作为任意 HTTP 服务托管进沙箱由 OpenSandbox server 负责拉起容器并管理生命周期SDK 负责在本地完成创建、健康检查与端口映射解析最终把网关服务暴露为宿主可达的127.0.0.1:端口形式。示例的自动化闭环是向 OpenSandbox server 请求创建一个以 Nullclaw 镜像为启动源、存活时间 1 小时的沙箱通过沙箱的 3000 端口端点轮询http://endpoint/health直到返回 HTTP 200就绪后打印最终可达的 Gateway 地址例如127.0.0.1:56234。这一模式并不局限于 Nullclaw——任何容器内跑 HTTP 服务 端口暴露的场景Webhook 网关、开发服务器、代理等都可以复用同样的 SDK 调用链。环境准备启动 OpenSandbox serverDocker 运行时前提OpenSandbox server 默认使用runtime.type docker因此必须能连上一个正在运行的 Docker daemonDocker Desktop保持其运行并用docker version验证ColimamacOS先启动colima start再导出 socketexport DOCKER_HOSTunix://${HOME}/.colima/default/docker.sock预拉取镜像并启动 serverNullclaw 容器镜像发布在 GHCR 上预拉取可显著缩短首次创建沙箱的时间docker pull ghcr.io/nullclaw/nullclaw:latest安装并启动 OpenSandbox server日志会留在终端中uv pip install opensandbox-server opensandbox-server init-config ~/.sandbox.toml --example docker opensandbox-server其中init-config生成的~/.sandbox.toml采用 docker 运行时配置模板server 默认监听localhost:8080与后文脚本中硬编码的服务地址一致。创建并访问 Nullclaw 沙箱参数约定该示例为快速上手做了硬编码见 main.py参数值说明OpenSandbox serverhttp://localhost:8080管理 API 地址镜像ghcr.io/nullclaw/nullclaw:latestNullclaw Gateway 容器Gateway 端口3000容器内监听端口用于get_endpoint与/health轮询超时3600s沙箱最大存活时间到期后自动回收安装依赖并运行从项目根目录安装 Python SDK 与requests健康检查轮询使用uv pip install opensandbox requests运行示例uv run python examples/nullclaw/main.py成功时的输出形如Creating nullclaw sandbox with imageghcr.io/nullclaw/nullclaw:latest on OpenSandbox server http://localhost:8080... [check] sandbox ready after 0.3s Nullclaw gateway started. Please refer to 127.0.0.1:56234最后一行打印的端点例如127.0.0.1:56234就是 OpenSandbox 从沙箱映射出来的 Nullclaw Gateway 地址可直接用curl访问其公开端点curl http://127.0.0.1:56234/health关于认证端点Nullclaw 默认要求先完成 pairing配对之后才能使用带认证的端点例如/webhook/health端点始终保持公开可访问——这也是本示例选它作为就绪判据的原因。脚本逐段解析对照源码健康检查函数check_nullclawcheck_nullclaw 是传给 SDK 的自定义同步健康检查返回True表示就绪False表示超时或异常def check_nullclaw(sbx: SandboxSync) - bool: try: endpoint sbx.get_endpoint(3000) start time.perf_counter() url fhttp://{endpoint.endpoint}/health 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: pass time.sleep(0.2) return False except Exception as exc: print(f[check] failed: {exc}) return False要点sbx.get_endpoint(3000)通过管理 API 解析 3000 端口在宿主侧的可达地址对应 SDK 中 SandboxSync.get_endpoint 的实现——它调用sandbox_service.get_sandbox_endpoint(self.id, port, use_server_proxy)把容器端口翻译为宿主可直连的endpoint字符串本地 docker 运行时下即127.0.0.1:映射端口轮询策略为单次请求 1 秒超时、间隔 0.2 秒、最多 150 次总等待上限约 30 秒任何网络异常都被吞掉继续轮询适合容器已启动但进程尚未 listen的窗口期。从 SDK 源码结构看SandboxSync.create收到health_check参数后会把它保存为custom_health_check并在 check_ready 流程中按health_check_polling_interval默认 200ms反复调用直到返回True或超过ready_timeout默认 30 秒。因此本例实际上有双层 30 秒预算内层是check_nullclaw自身的 150 次轮询外层是 SDK 的ready_timeout。创建沙箱的完整调用main 函数 中的一次性创建调用覆盖了 SDK 的关键能力面sandbox SandboxSync.create( imageimage, timeouttimedelta(secondstimeout_seconds), metadata{example: nullclaw}, connection_configConnectionConfigSync(domainserver), health_checkcheck_nullclaw, # use network policy to limit nullclaw network accesses network_policyNetworkPolicy( defaultActiondeny, egress[NetworkRule(actionallow, targetopenrouter.ai)], ), ) endpoint sandbox.get_endpoint(3000) print(fNullclaw gateway started. Please refer to {endpoint.endpoint})对照 SandboxSync.create 签名各参数语义如下image容器镜像引用字符串会被包装为SandboxImageSpec与snapshot_id二选一源码中有显式校验timeout3600s沙箱最大存活时间对应示例文档中Timeout: 3600s到期自动回收若传None则表示需要显式清理metadata自定义元数据这里打了一个example: nullclaw标记便于后续按元数据过滤沙箱列表connection_config指向本地 server 的同步连接配置health_check即上文轮询函数SDK 阻塞等待其通过后才返回network_policy出口网络策略下一节展开。另外可以注意 SDK 的默认行为未显式传resource时默认为{cpu: 1, memory: 2Gi}见 create 实现中的默认值未传entrypoint时默认[tail, -f, /dev/null——而 Nullclaw 镜像自带入口进程所以示例无需覆盖。ConnectionConfigSyncSDK 如何连到 serverConnectionConfigSync 是所有同步 SDK HTTP 客户端共享的连接配置本例只显式设置了domainhttp://localhost:8080其余走默认值字段默认值作用domainlocalhost:8080或OPEN_SANDBOX_DOMAIN环境变量管理 API 基地址自动拼接/v1protocolhttp仅接受http/httpsrequest_timeout30s管理 API 请求超时api_key环境变量OPEN_SANDBOX_API_KEY服务端开启鉴权时使用use_server_proxyFalse为True时让 server 代理 execd 请求适用于客户端无法直连沙箱端点的部署形态若未传入transportSDK 会为每个实例自建带重试与 deadline 控制的共享 transportwith_transport_if_missing见 连接配置实现这也是 SDK 具备弹性传输重试、超时收敛能力的基础。出口网络策略默认拒绝仅放行 openrouter.ai示例中最值得展开的一行是创建沙箱时附带的network_policynetwork_policyNetworkPolicy( defaultActiondeny, egress[NetworkRule(actionallow, targetopenrouter.ai)], )对照 SDK 模型定义 NetworkPolicy 与 NetworkRuledefault_action别名defaultAction未匹配任何规则时的默认动作默认即为deny即未列出的一律拒绝egress规则列表按顺序求值每条NetworkRule由actionallow/deny与targetFQDN 或通配域名如*.example.com组成target为空会直接校验失败。也就是说这个 Nullclaw 沙箱在数据面只被允许出站到openrouter.aiNullclaw 调用大模型 API 的目标域名其余所有外网访问都会被拦截。NetworkPolicy的模型注释明确指出它与 egress sidecar 的/policy请求体保持一致——从源码结构看策略由 OpenSandbox 的 egress 组件独立组件目录 components/egress在沙箱网络边界执行这正是 OpenSandboxFQDN 粒度出口管控能力在示例中的直接应用。这条策略体现了沙箱的典型安全姿态入向端口由 OpenSandbox 受控映射只有显式get_endpoint(3000)才暴露 3000 端口出向流量默认全断、白名单放行。对于承载 LLM 网关这类只需要打一个上游 API的负载这种最小化出口面几乎零成本。端到端流程小结把示例各角色串起来一次uv run python examples/nullclaw/main.py的完整链路是SDK 经ConnectionConfigSync(domainhttp://localhost:8080)调 server 管理 API携带镜像、1 小时超时、metadata 与deny-by-default出口策略创建沙箱server 通过 Docker 运行时拉起ghcr.io/nullclaw/nullclaw:latest容器首次前需docker pull预拉取并为 execd / egress / 业务端口建立可解析的端点SDK 用自定义health_check轮询get_endpoint(3000)映射出的http://host/health200 即就绪就绪后再次get_endpoint(3000)打印最终 Gateway 地址后续即可对该地址调用/health公开或完成 pairing 后的认证端点如/webhook。延伸阅读仓库内路径示例脚本与本地 READMEexamples/nullclaw/main.py、examples/nullclaw/README.mdPython SDK 沙箱创建与端点解析sdks/sandbox/python/src/opensandbox/sync/sandbox.pycreate见 L454 起get_endpoint见 L223 起同步连接配置sdks/sandbox/python/src/opensandbox/config/connection_sync.py网络策略模型sdks/sandbox/python/src/opensandbox/models/sandboxes.pyL117-L152egress 组件实现与文档components/egress/README.md、docs/components/egress.md服务端本地部署与配置server/README.md、server/configuration.md复现前提本机可运行的 Docker daemon、Python 3 环境与uv且 server 与示例脚本在同一台机器localhost:8080直连形态。若你的部署形态是 K8s 或其他运行时init-config与网络策略的落地方式会有差异应以 server 配置文档为准。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考