拓冰网站定制 
OpenSandbox CLIosb实战指南从终端到沙箱全生命周期管理【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于 OpenSandbox 仓库的 cli/README.md 展开完整覆盖osb命令行的安装、配置模型、沙箱创建、命令执行、文件操作、运行时出口策略、Credential Vault、诊断输出与 Agent Skills 等核心能力并结合仓库内 CLI 源码Click 命令实现、配置解析、SDK 客户端封装解释每条命令背后的实际行为帮助你在终端中快速搭建一条可复制、可运维的 OpenSandbox 工作流。1.osb的定位与总体结构osb是 OpenSandbox 的命令行接口面向日常高频操作场景创建和管理沙箱create / list / get / kill / pause / endpoint / metrics在沙箱内运行命令前台流式、后台跟踪执行、持久 shell 会话读取和修改沙箱内文件write / cat / upload / download / search / replace / chmod 等检查运行时出口egress策略并在线打补丁管理沙箱本地的 Credential Vault 状态采集底层诊断信息logs / events为编码 Agent 安装 OpenSandbox 专用的 Skills从源码结构看CLI 底层直接使用 OpenSandbox Python SDKclient.py 中的ClientContext通过ConnectionConfigSync和SandboxManagerSync来自opensandbox.sync.manager/opensandbox.sync.sandbox与服务器通信CLI 本身是 SDK 之上的一层命令封装。因此 CLI 的能力边界与 SDK 同步 API 保持一致。pyproject.toml 声明了两个可执行入口[project.scripts] opensandbox opensandbox_cli.main:cli osb opensandbox_cli.main:cli要求 Python3.10核心依赖为opensandbox0.1.9,0.2.0、click、rich、pyyaml。根命令定义在 main.py注册了 9 个命令组命令组职责源码osb sandbox沙箱生命周期管理commands/sandbox.pyosb command命令执行与持久会话commands/command.pyosb file文件与目录操作commands/file.pyosb egress运行时出口策略commands/egress.pyosb credential-vaultCredential Vault 状态管理commands/credential_vault.pyosb diagnostics稳定的 logs / events 诊断commands/diagnostics.pyosb devops实验性遗留诊断commands/devops.pyosb config本地 CLI 配置commands/config_cmd.pyosb skills内置 Skills 的安装与管理commands/skills.py2. 安装三种安装方式任选其一pip install opensandbox-cliuv tool install opensandbox-clipipx install opensandbox-cli安装后验证osb --help osb --version根命令支持的全局选项见 main.py--api-key认证用 API Key--domainAPI 服务器地址如localhost:8080--protocolhttp/https--request-timeout请求超时秒--use-server-proxy / --no-use-server-proxy是否让 execd 与 endpoint 流量经由沙箱服务器代理转发--config指定配置文件路径对整个调用生效-v / --verbose开启 DEBUG 日志--no-color关闭彩色输出前置条件确保 OpenSandbox 服务器可达。本地开发时先启动服务器再让 CLI 指向它opensandbox-server仓库内本地开发如果直接在当前 monorepo 中开发见 cli/README.md 的 Development 一节cd cli uv sync uv run osb --help uv run pytest值得注意的是 pyproject.toml 通过[tool.uv.sources]将opensandboxSDK 指向本地路径../sdks/sandbox/pythoneditable因此从cli/目录运行时会解析到仓库内检出的 SDK 源码而不是 PyPI 上的发布版本——这是验证 SDK/CLI 联动改动时的适用前提。3. 配置模型四级优先级CLI 的配置解析顺序在 config.py 中实现从源码的resolve_config()合并逻辑可以确认优先级从高到低为根命令级 CLI 参数--api-key、--domain、--protocol、--request-timeout、--config环境变量OPEN_SANDBOX_API_KEY、OPEN_SANDBOX_DOMAIN、OPEN_SANDBOX_PROTOCOL、OPEN_SANDBOX_REQUEST_TIMEOUT、OPEN_SANDBOX_USE_SERVER_PROXY配置文件默认~/.opensandbox/config.tomlSDK 默认值各连接项在代码中的默认值为protocol缺省http、request_timeout缺省30秒、use_server_proxy缺省false、color缺省true见 config.py。配置命令osb config init osb config show osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set connection.api_key your-api-key osb config set defaults.image python:3.12 osb config set defaults.timeout 30mosb config init会在~/.opensandbox/config.toml写入一份全注释的模板由 config.py 的DEFAULT_CONFIG_TEMPLATE生成文件已存在时会报错需要显式--force覆盖。若某次调用要使用非默认配置文件需在根命令层通过--config指定对整次调用生效osb --config /tmp/dev.toml config init osb --config /tmp/dev.toml config set connection.domain localhost:8080 osb --config /tmp/dev.toml config show -o json一份完整的配置文件示例[connection] api_key your-api-key domain localhost:8080 protocol http request_timeout 30 use_server_proxy false [output] color true [defaults] image python:3.12 timeout 30m[defaults]中的image/timeout会被 sandbox.py 的create命令读取--image缺省时回落到defaults.image两者都未提供则报错--timeout缺省时回落到defaults.timeout仍缺省则交给 SDK 的默认 TTL。4. Quick Start六步走通一条沙箱工作流4.1 初始化配置osb config init osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set connection.api_key your-api-key osb config show -o json4.2 创建沙箱osb sandbox create --image python:3.12 --timeout 30m -o json如果已经设置好 defaults后续创建可以更短osb config set defaults.image python:3.12 osb config set defaults.timeout 30m osb sandbox create -o json4.3 验证可用性osb sandbox get sandbox-id -o json osb sandbox health sandbox-id -o json4.4 在沙箱内运行命令注意在沙箱命令载荷前使用--分隔osb command run sandbox-id -o raw -- python -c print(1 1)4.5 读写文件osb file write sandbox-id /workspace/hello.txt -c hello -o json osb file cat sandbox-id /workspace/hello.txt -o raw4.6 清理osb sandbox kill sandbox-id -o json5. 创建沙箱osb sandbox create全参数解析基础创建osb sandbox create --image python:3.12私有镜像凭据必须成对出现sandbox.py 会校验 username/password 必须同时提供osb sandbox create \ --image my-registry.example.com/team/app:latest \ --image-auth-username alice \ --image-auth-password token手动清理模式不设 TTLosb sandbox create --image python:3.12 --timeout none显式指定 entrypoint argv--entrypoint可重复逐项拼装完整 argv见 sandbox.pyosb sandbox create \ --image python:3.12 \ --entrypoint python \ --entrypoint -m \ --entrypoint http.server带网络策略与卷osb sandbox create \ --image python:3.12 \ --network-policy-file network-policy.json \ --volumes-file volumes.json启用 Credential Vault 透明代理osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json从源码看--credential-proxy有硬约束它要求同时提供--network-policy-file否则在 sandbox.py 中直接抛出--credential-proxy requires --network-policy-file because Credential Vault injection needs egress policy。策略文件被解析为 SDK 的NetworkPolicy对象卷文件必须是一个 JSON 数组逐项构造为Volume对象sandbox.py。create还支持 README 未逐一列出、但源码中存在的可重复 KV 参数可用于更精细的控制osb sandbox create \ --image python:3.12 \ --env KEYVALUE \ --metadata owneralice \ --extension kv \ --resource cpu1 memory2Gi \ --ready-timeout 30s \ --skip-health-check -o json--env / -e注入环境变量可重复--metadata / -m附加元数据可重复也可用于list的过滤--extension扩展参数可重复--resource资源限制如cpu1 memory2Gi可重复--skip-health-check不等待沙箱就绪--ready-timeout等待就绪的最长时间如30s6. 列举、检查与生命周期操作osb sandbox list osb sandbox list -o json osb sandbox list --state running --state paused osb sandbox get sandbox-id -o json osb sandbox metrics sandbox-id osb sandbox metrics sandbox-id --watch -o raw从 sandbox.py 看list的状态过滤会先把大小写归一化到 SDKSandboxState枚举Pending/Running/Paused等非法状态值会列出全部合法取值还支持--metadata KEYVALUE过滤以及--page/--page-size分页。暂停沙箱注意异步语义Pause 是异步操作。Pause request accepted只表示服务器接受了请求不代表沙箱已进入Paused状态。需要轮询直到状态迁移完成osb sandbox pause sandbox-id osb sandbox get sandbox-id -o json暴露服务端口osb sandbox endpoint sandbox-id --port 8080 -o json7. 命令执行前台流式、后台跟踪、持久会话前台流式输出-o raw直接输出原始流osb command run sandbox-id -o raw -- sh -lc echo ready后台跟踪执行拿到execution-id后可查询状态、拉取日志osb command run sandbox-id --background -o json -- sh -c sleep 10; echo done osb command status sandbox-id execution-id -o json osb command logs sandbox-id execution-id -o json持久 shell 会话同一个 session 内环境变量、工作目录会保持osb command session create sandbox-id --workdir /workspace -o json osb command session run sandbox-id session-id -o raw -- pwd osb command session run sandbox-id session-id -o raw -- export FOObar osb command session run sandbox-id session-id -o raw -- sh -c echo $FOO osb command session delete sandbox-id session-id -o json8. 文件操作README 覆盖的核心用法osb file upload sandbox-id ./local.txt /workspace/local.txt -o json osb file download sandbox-id /workspace/result.json ./result.json -o json osb file search sandbox-id /workspace --pattern *.py -o json osb file info sandbox-id /workspace/main.py -o json osb file replace sandbox-id /workspace/app.py --old old --new new -o json osb file chmod sandbox-id /workspace/script.sh --mode 755 -o json从 file.py 的注册情况看file组还包含rm、mv、mkdir、rmdir子命令write在未提供-c内容时从 stdin 读取且支持--mode/--owner/--group控制文件属主与权限search的--pattern是 glob 模式且为必填项。这些与 Quick Start 中的file write/file cat配合可以在终端完成沙箱内文件的完整 CRUD。9. 运行时出口egress策略检查当前策略osb egress get sandbox-id -o json按需打补丁--rule支持allow/deny前缀解析逻辑见 egress.py 的_parse_ruleosb egress patch sandbox-id --rule allowpypi.org --rule denyinternal.example.com -o json调试连通性时用真实命令验证行为最直观osb command run sandbox-id -o raw -- curl -I https://pypi.org10. 管理 Credential VaultCredential Vault 操作通过 Python SDK 调用沙箱的 egress sidecar。必须先以--credential-proxy加显式网络策略创建沙箱再写入 vault 状态osb credential-vault create sandbox-id --file vault.yaml -o json osb credential-vault get sandbox-id -o json osb credential-vault patch sandbox-id --file mutation.yaml -o json osb credential-vault credential list sandbox-id -o json osb credential-vault binding list sandbox-id -o json osb credential-vault delete sandbox-id -o json安全要点--file -表示从 stdin 读取 JSON/YAML 载荷不要把明文凭证值作为命令行参数传入应放在载荷流或文件中避免进入 shell 历史记录与进程列表。源码中create/patch的载荷读取辅助函数见 credential_vault.py。11. 诊断稳定的 diagnostics 与实验性的 devops使用稳定的、API 支撑的日志与事件诊断命令osb diagnostics events sandbox-id --scope runtime -o raw osb diagnostics events sandbox-id --scope all -o raw osb diagnostics logs sandbox-id --scope container -o raw osb diagnostics logs sandbox-id --scope all -o json osb diagnostics events sandbox-id --scope runtime -o json osb diagnostics logs sandbox-id --scope container -o yaml关键规则README 明确说明diagnostics.py 中--scope为必填参数--scope是稳定诊断的必填项。内置服务器支持的取值为logs 用container/allevents 用runtime/all不可用的 scope 会返回DIAGNOSTICS_SCOPE_UNSUPPORTED包括 lifecycle eventsbest-effort scope 可能只返回部分后端内容此时结果中会带warnings字段raw 输出直接打印诊断文本若诊断以临时 URL 下发则打印该 URL结构化输出遵循 SDK/Python 字段风格例如content_url、content_length、expires_at较旧的服务器构建对 scope 诊断可能返回DIAGNOSTICS_NOT_IMPLEMENTED。遗留的 DevOps 诊断仍属实验性质稳定场景优先用osb diagnostics logs/eventsosb devops inspect sandbox-id -o raw osb devops summary sandbox-id -o raw12. 输出格式按命令作用域选择输出格式选择是命令级的-o/--output不是全局的table人类可读的表格与面板json机器可读 JSONyaml机器可读 YAMLraw未格式化的文本或流式输出示例osb sandbox list -o json osb sandbox list -o yaml osb file cat sandbox-id /workspace/hello.txt -o raw并非每个命令都支持每种格式例如create只允许 table/json/yaml见 sandbox.py拿不准时对具体命令执行--help即可看到允许的取值与缺省值。13. Agent Skills把操作手册装进编码 AgentCLI 内置了面向编码 Agent 和 Agent 工具的 OpenSandbox skills。README 列出的内置 skills 包括sandbox-lifecycle创建、检查、续期、暂停、恢复、终止沙箱的标准流程command-execution前台/后台命令、状态与日志、持久会话file-operations沙箱内文件的读、写、上传、下载、搜索、替换network-egress查看与修补出口 allow/deny 规则sandbox-troubleshooting故障沙箱的分诊与修复步骤从源码结构看skill_registry.py 的BUILTIN_SKILLS注册表实际上还定义了第六个credential-vaultskill覆盖凭证与绑定的运行时管理其 Markdown 源文件位于 skills 目录以opensandbox-*.md命名随包发布。支持的目标与安装位置Target安装位置claude./.claude/skills/或~/.claude/skills/cursor./.cursor/rules/或~/.cursor/rules/codex./.codex/skills/name/SKILL.md或~/.codex/skills/name/SKILL.mdcopilot./.github/copilot-instructions.md或~/.github/copilot-instructions.mdwindsurf./.windsurfrules或~/.windsurfrulescline./.clinerules或~/.clinerulesopencode./.agents/skills/name/SKILL.md或~/.agents/skills/name/SKILL.md常用流程osb skills list osb skills show sandbox-lifecycle osb skills install sandbox-lifecycle --target codex --scope project osb skills install --all-builtins --target codex --scope global osb skills uninstall sandbox-troubleshooting --target claude --scope global脚本或 Agent 集成时使用结构化输出osb skills install sandbox-lifecycle --target codex --scope project -o json从实现看skill_registry.py 的render_skill_for_target不同目标会按自身约定渲染需要保留 frontmatter 的目标直接输出原文否则将 YAML frontmatter 折叠为# 标题 摘要的纯 Markdown 形式以适配各工具对规则文件的解析要求。14. 小结与深入参考osb的设计思路是终端到工作流的最短路径所有操作都走 OpenSandbox Python SDK 的同步 API配置按 CLI 参数 环境变量 配置文件 SDK 默认值四级合并输出格式命令级可控且把高频运维动作生命周期、命令执行、文件、egress、Credential Vault、诊断都收敛为一组语义明确的命令。继续深入时建议按以下路径阅读仓库cli/README.md官方 CLI 文档本文骨架来源cli/src/opensandbox_cli/main.py根命令与全局选项cli/src/opensandbox_cli/config.py配置解析与优先级实现cli/src/opensandbox_cli/client.pyClientContext与 SDK 客户端封装cli/src/opensandbox_cli/commands/各命令组实现cli/tests/test_commands.py、test_config.py、test_skills.py等测试可验证上述命令行为docs/cli/index.md文档站中的 CLI 章节入口适用前提提醒本文所有命令、参数与行为均以当前仓库cli/目录的实际内容为准CLI 依赖opensandbox0.1.9,0.2.0的 SDK 同步接口且需要可达的 OpenSandbox 服务器本地可用opensandbox-server启动部分服务器端能力如 scope 诊断在旧版本构建上可能返回DIAGNOSTICS_NOT_IMPLEMENTED。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenSandbox CLI（osb）实战指南：从终端到沙箱全生命周期管理
OpenSandbox CLIosb实战指南从终端到沙箱全生命周期管理【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox本文基于 OpenSandbox 仓库的 cli/README.md 展开完整覆盖osb命令行的安装、配置模型、沙箱创建、命令执行、文件操作、运行时出口策略、Credential Vault、诊断输出与 Agent Skills 等核心能力并结合仓库内 CLI 源码Click 命令实现、配置解析、SDK 客户端封装解释每条命令背后的实际行为帮助你在终端中快速搭建一条可复制、可运维的 OpenSandbox 工作流。1.osb的定位与总体结构osb是 OpenSandbox 的命令行接口面向日常高频操作场景创建和管理沙箱create / list / get / kill / pause / endpoint / metrics在沙箱内运行命令前台流式、后台跟踪执行、持久 shell 会话读取和修改沙箱内文件write / cat / upload / download / search / replace / chmod 等检查运行时出口egress策略并在线打补丁管理沙箱本地的 Credential Vault 状态采集底层诊断信息logs / events为编码 Agent 安装 OpenSandbox 专用的 Skills从源码结构看CLI 底层直接使用 OpenSandbox Python SDKclient.py 中的ClientContext通过ConnectionConfigSync和SandboxManagerSync来自opensandbox.sync.manager/opensandbox.sync.sandbox与服务器通信CLI 本身是 SDK 之上的一层命令封装。因此 CLI 的能力边界与 SDK 同步 API 保持一致。pyproject.toml 声明了两个可执行入口[project.scripts] opensandbox opensandbox_cli.main:cli osb opensandbox_cli.main:cli要求 Python3.10核心依赖为opensandbox0.1.9,0.2.0、click、rich、pyyaml。根命令定义在 main.py注册了 9 个命令组命令组职责源码osb sandbox沙箱生命周期管理commands/sandbox.pyosb command命令执行与持久会话commands/command.pyosb file文件与目录操作commands/file.pyosb egress运行时出口策略commands/egress.pyosb credential-vaultCredential Vault 状态管理commands/credential_vault.pyosb diagnostics稳定的 logs / events 诊断commands/diagnostics.pyosb devops实验性遗留诊断commands/devops.pyosb config本地 CLI 配置commands/config_cmd.pyosb skills内置 Skills 的安装与管理commands/skills.py2. 安装三种安装方式任选其一pip install opensandbox-cliuv tool install opensandbox-clipipx install opensandbox-cli安装后验证osb --help osb --version根命令支持的全局选项见 main.py--api-key认证用 API Key--domainAPI 服务器地址如localhost:8080--protocolhttp/https--request-timeout请求超时秒--use-server-proxy / --no-use-server-proxy是否让 execd 与 endpoint 流量经由沙箱服务器代理转发--config指定配置文件路径对整个调用生效-v / --verbose开启 DEBUG 日志--no-color关闭彩色输出前置条件确保 OpenSandbox 服务器可达。本地开发时先启动服务器再让 CLI 指向它opensandbox-server仓库内本地开发如果直接在当前 monorepo 中开发见 cli/README.md 的 Development 一节cd cli uv sync uv run osb --help uv run pytest值得注意的是 pyproject.toml 通过[tool.uv.sources]将opensandboxSDK 指向本地路径../sdks/sandbox/pythoneditable因此从cli/目录运行时会解析到仓库内检出的 SDK 源码而不是 PyPI 上的发布版本——这是验证 SDK/CLI 联动改动时的适用前提。3. 配置模型四级优先级CLI 的配置解析顺序在 config.py 中实现从源码的resolve_config()合并逻辑可以确认优先级从高到低为根命令级 CLI 参数--api-key、--domain、--protocol、--request-timeout、--config环境变量OPEN_SANDBOX_API_KEY、OPEN_SANDBOX_DOMAIN、OPEN_SANDBOX_PROTOCOL、OPEN_SANDBOX_REQUEST_TIMEOUT、OPEN_SANDBOX_USE_SERVER_PROXY配置文件默认~/.opensandbox/config.tomlSDK 默认值各连接项在代码中的默认值为protocol缺省http、request_timeout缺省30秒、use_server_proxy缺省false、color缺省true见 config.py。配置命令osb config init osb config show osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set connection.api_key your-api-key osb config set defaults.image python:3.12 osb config set defaults.timeout 30mosb config init会在~/.opensandbox/config.toml写入一份全注释的模板由 config.py 的DEFAULT_CONFIG_TEMPLATE生成文件已存在时会报错需要显式--force覆盖。若某次调用要使用非默认配置文件需在根命令层通过--config指定对整次调用生效osb --config /tmp/dev.toml config init osb --config /tmp/dev.toml config set connection.domain localhost:8080 osb --config /tmp/dev.toml config show -o json一份完整的配置文件示例[connection] api_key your-api-key domain localhost:8080 protocol http request_timeout 30 use_server_proxy false [output] color true [defaults] image python:3.12 timeout 30m[defaults]中的image/timeout会被 sandbox.py 的create命令读取--image缺省时回落到defaults.image两者都未提供则报错--timeout缺省时回落到defaults.timeout仍缺省则交给 SDK 的默认 TTL。4. Quick Start六步走通一条沙箱工作流4.1 初始化配置osb config init osb config set connection.domain localhost:8080 osb config set connection.protocol http osb config set connection.api_key your-api-key osb config show -o json4.2 创建沙箱osb sandbox create --image python:3.12 --timeout 30m -o json如果已经设置好 defaults后续创建可以更短osb config set defaults.image python:3.12 osb config set defaults.timeout 30m osb sandbox create -o json4.3 验证可用性osb sandbox get sandbox-id -o json osb sandbox health sandbox-id -o json4.4 在沙箱内运行命令注意在沙箱命令载荷前使用--分隔osb command run sandbox-id -o raw -- python -c print(1 1)4.5 读写文件osb file write sandbox-id /workspace/hello.txt -c hello -o json osb file cat sandbox-id /workspace/hello.txt -o raw4.6 清理osb sandbox kill sandbox-id -o json5. 创建沙箱osb sandbox create全参数解析基础创建osb sandbox create --image python:3.12私有镜像凭据必须成对出现sandbox.py 会校验 username/password 必须同时提供osb sandbox create \ --image my-registry.example.com/team/app:latest \ --image-auth-username alice \ --image-auth-password token手动清理模式不设 TTLosb sandbox create --image python:3.12 --timeout none显式指定 entrypoint argv--entrypoint可重复逐项拼装完整 argv见 sandbox.pyosb sandbox create \ --image python:3.12 \ --entrypoint python \ --entrypoint -m \ --entrypoint http.server带网络策略与卷osb sandbox create \ --image python:3.12 \ --network-policy-file network-policy.json \ --volumes-file volumes.json启用 Credential Vault 透明代理osb sandbox create --image python:3.12 --network-policy-file network-policy.json --credential-proxy -o json从源码看--credential-proxy有硬约束它要求同时提供--network-policy-file否则在 sandbox.py 中直接抛出--credential-proxy requires --network-policy-file because Credential Vault injection needs egress policy。策略文件被解析为 SDK 的NetworkPolicy对象卷文件必须是一个 JSON 数组逐项构造为Volume对象sandbox.py。create还支持 README 未逐一列出、但源码中存在的可重复 KV 参数可用于更精细的控制osb sandbox create \ --image python:3.12 \ --env KEYVALUE \ --metadata owneralice \ --extension kv \ --resource cpu1 memory2Gi \ --ready-timeout 30s \ --skip-health-check -o json--env / -e注入环境变量可重复--metadata / -m附加元数据可重复也可用于list的过滤--extension扩展参数可重复--resource资源限制如cpu1 memory2Gi可重复--skip-health-check不等待沙箱就绪--ready-timeout等待就绪的最长时间如30s6. 列举、检查与生命周期操作osb sandbox list osb sandbox list -o json osb sandbox list --state running --state paused osb sandbox get sandbox-id -o json osb sandbox metrics sandbox-id osb sandbox metrics sandbox-id --watch -o raw从 sandbox.py 看list的状态过滤会先把大小写归一化到 SDKSandboxState枚举Pending/Running/Paused等非法状态值会列出全部合法取值还支持--metadata KEYVALUE过滤以及--page/--page-size分页。暂停沙箱注意异步语义Pause 是异步操作。Pause request accepted只表示服务器接受了请求不代表沙箱已进入Paused状态。需要轮询直到状态迁移完成osb sandbox pause sandbox-id osb sandbox get sandbox-id -o json暴露服务端口osb sandbox endpoint sandbox-id --port 8080 -o json7. 命令执行前台流式、后台跟踪、持久会话前台流式输出-o raw直接输出原始流osb command run sandbox-id -o raw -- sh -lc echo ready后台跟踪执行拿到execution-id后可查询状态、拉取日志osb command run sandbox-id --background -o json -- sh -c sleep 10; echo done osb command status sandbox-id execution-id -o json osb command logs sandbox-id execution-id -o json持久 shell 会话同一个 session 内环境变量、工作目录会保持osb command session create sandbox-id --workdir /workspace -o json osb command session run sandbox-id session-id -o raw -- pwd osb command session run sandbox-id session-id -o raw -- export FOObar osb command session run sandbox-id session-id -o raw -- sh -c echo $FOO osb command session delete sandbox-id session-id -o json8. 文件操作README 覆盖的核心用法osb file upload sandbox-id ./local.txt /workspace/local.txt -o json osb file download sandbox-id /workspace/result.json ./result.json -o json osb file search sandbox-id /workspace --pattern *.py -o json osb file info sandbox-id /workspace/main.py -o json osb file replace sandbox-id /workspace/app.py --old old --new new -o json osb file chmod sandbox-id /workspace/script.sh --mode 755 -o json从 file.py 的注册情况看file组还包含rm、mv、mkdir、rmdir子命令write在未提供-c内容时从 stdin 读取且支持--mode/--owner/--group控制文件属主与权限search的--pattern是 glob 模式且为必填项。这些与 Quick Start 中的file write/file cat配合可以在终端完成沙箱内文件的完整 CRUD。9. 运行时出口egress策略检查当前策略osb egress get sandbox-id -o json按需打补丁--rule支持allow/deny前缀解析逻辑见 egress.py 的_parse_ruleosb egress patch sandbox-id --rule allowpypi.org --rule denyinternal.example.com -o json调试连通性时用真实命令验证行为最直观osb command run sandbox-id -o raw -- curl -I https://pypi.org10. 管理 Credential VaultCredential Vault 操作通过 Python SDK 调用沙箱的 egress sidecar。必须先以--credential-proxy加显式网络策略创建沙箱再写入 vault 状态osb credential-vault create sandbox-id --file vault.yaml -o json osb credential-vault get sandbox-id -o json osb credential-vault patch sandbox-id --file mutation.yaml -o json osb credential-vault credential list sandbox-id -o json osb credential-vault binding list sandbox-id -o json osb credential-vault delete sandbox-id -o json安全要点--file -表示从 stdin 读取 JSON/YAML 载荷不要把明文凭证值作为命令行参数传入应放在载荷流或文件中避免进入 shell 历史记录与进程列表。源码中create/patch的载荷读取辅助函数见 credential_vault.py。11. 诊断稳定的 diagnostics 与实验性的 devops使用稳定的、API 支撑的日志与事件诊断命令osb diagnostics events sandbox-id --scope runtime -o raw osb diagnostics events sandbox-id --scope all -o raw osb diagnostics logs sandbox-id --scope container -o raw osb diagnostics logs sandbox-id --scope all -o json osb diagnostics events sandbox-id --scope runtime -o json osb diagnostics logs sandbox-id --scope container -o yaml关键规则README 明确说明diagnostics.py 中--scope为必填参数--scope是稳定诊断的必填项。内置服务器支持的取值为logs 用container/allevents 用runtime/all不可用的 scope 会返回DIAGNOSTICS_SCOPE_UNSUPPORTED包括 lifecycle eventsbest-effort scope 可能只返回部分后端内容此时结果中会带warnings字段raw 输出直接打印诊断文本若诊断以临时 URL 下发则打印该 URL结构化输出遵循 SDK/Python 字段风格例如content_url、content_length、expires_at较旧的服务器构建对 scope 诊断可能返回DIAGNOSTICS_NOT_IMPLEMENTED。遗留的 DevOps 诊断仍属实验性质稳定场景优先用osb diagnostics logs/eventsosb devops inspect sandbox-id -o raw osb devops summary sandbox-id -o raw12. 输出格式按命令作用域选择输出格式选择是命令级的-o/--output不是全局的table人类可读的表格与面板json机器可读 JSONyaml机器可读 YAMLraw未格式化的文本或流式输出示例osb sandbox list -o json osb sandbox list -o yaml osb file cat sandbox-id /workspace/hello.txt -o raw并非每个命令都支持每种格式例如create只允许 table/json/yaml见 sandbox.py拿不准时对具体命令执行--help即可看到允许的取值与缺省值。13. Agent Skills把操作手册装进编码 AgentCLI 内置了面向编码 Agent 和 Agent 工具的 OpenSandbox skills。README 列出的内置 skills 包括sandbox-lifecycle创建、检查、续期、暂停、恢复、终止沙箱的标准流程command-execution前台/后台命令、状态与日志、持久会话file-operations沙箱内文件的读、写、上传、下载、搜索、替换network-egress查看与修补出口 allow/deny 规则sandbox-troubleshooting故障沙箱的分诊与修复步骤从源码结构看skill_registry.py 的BUILTIN_SKILLS注册表实际上还定义了第六个credential-vaultskill覆盖凭证与绑定的运行时管理其 Markdown 源文件位于 skills 目录以opensandbox-*.md命名随包发布。支持的目标与安装位置Target安装位置claude./.claude/skills/或~/.claude/skills/cursor./.cursor/rules/或~/.cursor/rules/codex./.codex/skills/name/SKILL.md或~/.codex/skills/name/SKILL.mdcopilot./.github/copilot-instructions.md或~/.github/copilot-instructions.mdwindsurf./.windsurfrules或~/.windsurfrulescline./.clinerules或~/.clinerulesopencode./.agents/skills/name/SKILL.md或~/.agents/skills/name/SKILL.md常用流程osb skills list osb skills show sandbox-lifecycle osb skills install sandbox-lifecycle --target codex --scope project osb skills install --all-builtins --target codex --scope global osb skills uninstall sandbox-troubleshooting --target claude --scope global脚本或 Agent 集成时使用结构化输出osb skills install sandbox-lifecycle --target codex --scope project -o json从实现看skill_registry.py 的render_skill_for_target不同目标会按自身约定渲染需要保留 frontmatter 的目标直接输出原文否则将 YAML frontmatter 折叠为# 标题 摘要的纯 Markdown 形式以适配各工具对规则文件的解析要求。14. 小结与深入参考osb的设计思路是终端到工作流的最短路径所有操作都走 OpenSandbox Python SDK 的同步 API配置按 CLI 参数 环境变量 配置文件 SDK 默认值四级合并输出格式命令级可控且把高频运维动作生命周期、命令执行、文件、egress、Credential Vault、诊断都收敛为一组语义明确的命令。继续深入时建议按以下路径阅读仓库cli/README.md官方 CLI 文档本文骨架来源cli/src/opensandbox_cli/main.py根命令与全局选项cli/src/opensandbox_cli/config.py配置解析与优先级实现cli/src/opensandbox_cli/client.pyClientContext与 SDK 客户端封装cli/src/opensandbox_cli/commands/各命令组实现cli/tests/test_commands.py、test_config.py、test_skills.py等测试可验证上述命令行为docs/cli/index.md文档站中的 CLI 章节入口适用前提提醒本文所有命令、参数与行为均以当前仓库cli/目录的实际内容为准CLI 依赖opensandbox0.1.9,0.2.0的 SDK 同步接口且需要可达的 OpenSandbox 服务器本地可用opensandbox-server启动部分服务器端能力如 scope 诊断在旧版本构建上可能返回DIAGNOSTICS_NOT_IMPLEMENTED。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考