沙箱生命周期

rayrun run —— 创建并启动

同步创建（含启动握手，最长约 15 秒）；成功后返回，执行结果走 rayrun events。

rayrun run --name demo --cpus 2 --memory 2048
rayrun run --name demo-net --egress-allow pypi.org,files.pythonhosted.org
rayrun run --name demo-web --publish 8080

参数	说明
--name <name>	沙箱名（必填，≤ 64 字符；同客户内活跃沙箱唯一）
--agent <name@version>	agent 镜像（缺省 claude-code@1）
--cpus <n>	vCPU 数（≥ 1，默认 2）
--memory <mb>	内存基准 MiB（≥ 512，默认 2048）
--memory-max <mb>	内存气球上限 MiB（≥ --memory）
--workspace <mb>	工作区 MiB（默认 32768 = 32 GiB）
--max-lifetime <sec>	最长存活秒数（缺省 = 不限制，需显式 sandbox rm）
--credentials <names>	逗号分隔的凭证名（必须已由 credentials set 存在）
--egress-allow <list>	逗号分隔的域名/CIDR 白名单（缺省 = 完全断网）
--egress-deny <list>	逗号分隔的域名/CIDR 黑名单（allow 优先；域名仅 DNS 层生效）
--egress-allow-all	默认放行全部出网，deny 从中排除
--bandwidth <mbps>	出向带宽上限（默认 100，创建时固化）
--publish <port>[/<proto>]	发布沙箱内端口，可重复：8080 / 8080/http（等价，明文回连）/ 8443/https（沙箱内服务自持 TLS，平台回连时不校验证书）。入向走宿主 nginx 的 L7 反代，宿主不占端口；对外 URL 始终是 https。⚠️ CLI 不带可见性参数，服务端按默认 token 档创建；token 档当前恒 403（Q3 前）—— 要公开访问请在控制台「服务」页或 PUT /v1/sandboxes/:id/ingress/:port 显式传 visibility=public

rayrun sandbox —— 查看、销毁与生命周期

rayrun sandbox list          # 列出全部沙箱：ID、状态、规格
rayrun sandbox get <id>      # 查看单个沙箱详情
rayrun sandbox rm <id>       # 销毁沙箱（已销毁再删 = 幂等成功）

rayrun sandbox stop <id>     # 冷停：保留工作区与 IP，可再 start
rayrun sandbox start <id>    # 冷启动已停止的沙箱
rayrun sandbox pause <id>    # 真挂起：进程与内存保留
rayrun sandbox resume <id>   # 恢复已暂停的沙箱

• stop / start 是冷停 / 冷启动：停止期间没有进程，工作区与 IP 保留； start 走一次冷启动。
• pause / resume 是真挂起 / 恢复：进程与内存都保留，恢复更快。
• 四个动作都幂等：已处于目标状态时重复调用也返回成功。已停止的沙箱用 start 恢复，不能 resume。

list / get 加 --json 输出原始 JSON。销毁不可逆，工作区数据一并删除。

运行期修改出网策略

rayrun sandbox egress <id> --allow api.example.com,10.0.0.0/8 --deny blocked.example.com
rayrun sandbox egress <id> --allow-all --deny 10.0.0.0/8
rayrun sandbox egress <id> --clear      # 显式清空 = 完全断网

全量替换：未给的列表就是空，不保留旧值。allow 优先（同一目标同时命中 allow/deny 时放行）；--allow-all 下 deny 是黑名单，allow 条目是例外。 deny 中的域名只在 DNS 层拦截（直连 IP / DoH 可能绕过），CIDR 才是网络层边界。 带宽创建时固化、运行期不可改。Running / Paused / Stopped 均可修改；已销毁 沙箱会被拒绝。无任何策略参数时必须显式 --clear，避免误把沙箱断网。

生命周期与计费

只有「运行中」计费；停止与暂停期间只收存储费（见价格）。 停止、启动、暂停、恢复都可以在 CLI 里直接完成，控制台也提供同样的操作。