创建工作区沙箱¶
按规格、磁盘和网络设置创建托管沙箱。这个操作会分配运行资源,应先检查配额,并保存返回的沙箱 ID 用于回查和清理。
POST https://api.moi.matrixorigin.cn/v5/agent-sandboxes
调用前准备¶
准备目标工作区的个人访问令牌与相应操作权限;环境、令牌、工作区和沙箱 ID 保持一致。公共对象和结果确认说明资源身份、字段及状态。示例的资源值须替换为实际值。
请求¶
curl -X POST "https://api.moi.matrixorigin.cn/v5/agent-sandboxes" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
--data-binary '{"name":"audit-runner","compute_resource_id":"00000000-0000-0000-0000-000000000001","spec":"medium","disk_gi":10,"network_mode":"limited","network_tools":["git","curl"],"egress_endpoints":[{"host":"example.com","ports":[443]}]}'
字段 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
1~63 个 ASCII 字母、数字或内部连字符,首尾为字母或数字;支持大写。 |
|
string |
条件必填 |
已有可绑定计算资源 ID;启用计算绑定且无可解析默认资源时需提供。使用资源实例 ID,不用规格 ID。 |
|
string |
否 |
small、medium 或 large;省略/空值为 medium。 |
|
integer |
否 |
10~50 GiB;省略或 0 使用 10。 |
|
string |
否 |
limited 或 unrestricted;省略/空值为 limited。 |
|
string(字符串数组) |
否 |
limited 的工具允许列表;省略或空数组采用默认六工具。 |
|
object(对象数组) |
否 |
limited 的额外主机/端口允许列表,见公共网络对象。 |
unrestricted 需要部署显式允许,并且不能提交非空工具/端点列表。先用配额接口显式请求网络能力,不能根据字段缺失判断允许。默认工具、端点限制及创建/更新的不同空值语义见公共网络说明。
成功响应¶
{
"code": "OK",
"msg": "OK",
"data": {
"id": "sbx-example",
"workspace_id": "workspace-example",
"user_id": "user-example",
"name": "audit-runner",
"phase": "provisioning",
"edge_agent_id": "sbx-example",
"network_mode": "limited",
"network_tools": [
"git",
"curl"
],
"egress_endpoints": [
{
"host": "example.com",
"ports": [
443
]
}
],
"spec": "medium",
"disk_gi": 10,
"created_at": "2026-11-11T08:00:00Z",
"updated_at": "2026-11-11T08:00:00Z",
"update_available": null
}
}
HTTP 200 的数据含义如下;示例值不是默认配置。
字段 |
类型 |
说明 |
|---|---|---|
|
string |
成功时为 OK。 |
|
string |
响应说明。 |
|
object |
创建返回的沙箱快照,不保证已就绪。 |
结果确认¶
读取 data.id,继续查询详情确认 phase。只有实际 ready 且目标操作成功,才可认定可用;创建 HTTP 200 也可能返回 provisioning、unknown 或 error。响应未知时先查原请求与已有对象,不盲目换名创建多个资源。
错误处理¶
按 HTTP 状态及响应 code 判断;公共错误与恢复区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源,也不能当成重试或清理已经完成。