# 沙箱对象、网络和结果确认

托管沙箱属于工作区。先从当前列表或创建结果取得实际 ID，再读取阶段并使用目标能力；运行期临时沙箱与管理员跨工作区视图另有身份和范围。

## 沙箱字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 托管沙箱 ID，供详情、网络、终端和删除路径使用。 |
| `workspace_id` | string | 所属工作区。 |
| `user_id` | string | 创建者用户 ID。 |
| `name` | string | 显示名；支持 1～63 个 ASCII 字母/数字与内部连字符，不能替代 id。 |
| `phase` | string | unknown、provisioning、ready、error 或 deleting。成功取得响应不等于 ready。 |
| `edge_agent_id` | string | 服务使用的边缘智能体身份，不是另外可任意选择的沙箱路径 ID。 |
| `network_mode` | string | limited 或 unrestricted。 |
| `network_tools` | string（字符串数组） | 工具允许列表；为空时可能省略，结合网络模式判断。 |
| `egress_endpoints` | object（对象数组） | 额外出站主机/端口列表；为空时可能省略。 |
| `spec` | string | small、medium 或 large。 |
| `disk_gi` | integer | 磁盘容量，GiB。 |
| `compute_resource_id` | string | 有值时返回的计算资源实例 ID，不是规格名称。 |
| `created_at` | string | 创建时间，RFC 3339。 |
| `updated_at` | string | 更新时间，RFC 3339。 |
| `update_available` | boolean 或 null | 提供商可判断时为 true/false，否则为 null；未知不能按 false 解释。 |

工作区列表使用当前授权过滤，不是全局审计。会话临时运行资源不在该集合；创建登记尚未完成及删除中的对象也可被列表/详情隐藏。列表条数与配额占用可能不同。

## 网络设置

limited 工具允许值为 `git`、`pip`、`npm`、`go`、`cargo`、`curl`。重复工具会去重；创建时省略或传空工具数组采用这六项默认值。更新时两份列表都按完整目标替换，省略/null/[] 清空相应 MOI 管理列表，不保留旧值。

| 端点字段 | 类型 | 说明 |
| --- | --- | --- |
| `host` | string | 小写主机名；不带协议、路径、通配符、认证信息、端口或方括号。IP 字面量和 localhost 不合法。 |
| `ports` | integer（整数数组） | 必须有至少一个 1～65535 端口。 |

最多 256 个不同主机，每主机最多 16 个不同端口；同主机端口合并并去重。不能用 URL 或 `host:443` 替代 host/ports 两个字段。公共控制通道和提供商独立规则不由额外列表删除。

unrestricted 的创建需部署允许，且不能同时填写非空允许列表。配额 GET 只有显式 `include_network_capabilities=true` 时返回 `unrestricted_network_allowed`；旧形状缺失该字段不能当作 false 或 true。网络 PATCH 只替换 limited 的允许列表，不能切换模式，不能用它编辑 unrestricted。

## 生命周期与副作用

创建会分配运行资源，需配额、操作权限及部署启用；计算绑定启用时还需目标工作区内可绑定的资源实例或可解析的默认配置。请求返回对象可能仍为 provisioning/unknown/error；后续读取真实状态，并验证目标操作。

配额设置允许显式 0，省略字段保留；减少上限不会自动删除已有对象。当前占用结合远端资源和未完成的持久化分配，不能用可见列表长度代替。

网络写入失败会尝试恢复旧策略，恢复也可能失败。删除失败可能已经进入隐藏阶段；详情 404 或列表缺失只说明查询不可见，不能单独证明外部运行、凭据、计量及归属已全部清理。保留原 ID/请求标识，先回查再判断恢复操作。

## 终端与 SSH

[终端短期令牌](get-terminal-token.md)与[SSH 会话](create-ssh-session.md)是不同对象。终端 token 当前签发有效期 60 秒；WebSocket 连接建立后最多维持 30 分钟，并约每 30 秒重新检查当前角色/资源权限。不能把 token 有效期套用到已连接会话，也不能把原角色授权当作永久有效。

SSH 返回提供商网关信息与毫秒过期时间；申请成功不代表已经连接，具体连接由支持该网关协议的客户端处理。两种短期凭据均不得进入公开示例实值、审阅 Trace 或共享日志。

## 错误与恢复

| HTTP/代码 | 含义 | 处理 |
| --- | --- | --- |
| 401 / ErrUnauthorized | 身份或终端 token 认证失败。 | 检查当前环境凭据，不替换其他环境资源。 |
| 403 / SANDBOX_FORBIDDEN | 当前沙箱操作权限被拒绝。 | 检查目标工作区、资源和当前角色。 |
| 404 / SANDBOX_NOT_FOUND | 当前资源不存在或当前生命周期不可见。 | 回查原创建/删除记录，不根据 404 推断所有清理完成。 |
| 400 / SANDBOX_INVALID_NAME、SANDBOX_INVALID_SPEC 或 SANDBOX_EGRESS_* | 对应名称、规格/网络或端点校验错误。 | 按具体字段及限制修正；不同无效输入不保证映射为同一个错误码。 |
| 400 / SANDBOX_NETWORK_UNRESTRICTED_DISABLED | 部署未允许 unrestricted 创建。 | 显式读网络能力并选择允许模式。 |
| 400 / SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE | unrestricted 不接受允许列表更新。 | 不通过该接口切换网络模式。 |
| 409 / SANDBOX_QUOTA_EXCEEDED | 分配达到准入配额。 | 回查真实占用；按权限调整配置或清理已确认闲置资源。 |
| 409 / SANDBOX_REQUEST_CONFLICT | 同一请求身份对应不同创建输入。 | 保留原请求身份/输入并回查，不盲目复用到其他创建。 |
| 409 / SANDBOX_MANUAL_RECOVERY_REQUIRED、SANDBOX_WORKSPACE_DELETING | 需要恢复处理或工作区正在删除。 | 保留对象和请求身份，等待恢复或联系管理者。 |
| 503 / SANDBOX_IAM_UNAVAILABLE、SANDBOX_NETWORK_STORAGE_UNAVAILABLE | 授权或策略存储暂不可用。 | 保留请求和原策略，确认实际状态后再处理。 |
| 501 / SANDBOX_TERMINAL_NOT_CONFIGURED | 终端签名服务未配置。 | 确认部署配置，不能以注册路由推断终端可用。 |
| 500 / SANDBOX_ERROR | 其他当前服务错误。 | 保留脱敏请求标识并核查，不能将错误视为无副作用。 |

完整错误响应通常为 `{code,msg}`；终端升级后错误使用 WebSocket 消息，见[终端协议](terminal-websocket.md)，不再按普通 HTTP JSON 读取。
