# 创建工作区沙箱

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

按规格、磁盘和网络设置创建托管沙箱。这个操作会分配运行资源，应先检查配额，并保存返回的沙箱 ID 用于回查和清理。

```text
POST https://api.moi.matrixorigin.cn/v5/agent-sandboxes
```

## 调用前准备

准备目标工作区的个人访问令牌与相应操作权限；环境、令牌、工作区和沙箱 ID 保持一致。[公共对象和结果确认](objects.md)说明资源身份、字段及状态。示例的资源值须替换为实际值。

## 请求

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
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]}]}'
```

:::::
:::::{tab-item} 参数说明

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 1～63 个 ASCII 字母、数字或内部连字符，首尾为字母或数字；支持大写。 |
| `compute_resource_id` | string | 条件必填 | 已有可绑定计算资源 ID；启用计算绑定且无可解析默认资源时需提供。使用资源实例 ID，不用规格 ID。 |
| `spec` | string | 否 | small、medium 或 large；省略/空值为 medium。 |
| `disk_gi` | integer | 否 | 10～50 GiB；省略或 0 使用 10。 |
| `network_mode` | string | 否 | limited 或 unrestricted；省略/空值为 limited。 |
| `network_tools` | string（字符串数组） | 否 | limited 的工具允许列表；省略或空数组采用默认六工具。 |
| `egress_endpoints` | object（对象数组） | 否 | limited 的额外主机/端口允许列表，见公共网络对象。 |

unrestricted 需要部署显式允许，并且不能提交非空工具/端点列表。先用配额接口显式请求网络能力，不能根据字段缺失判断允许。默认工具、端点限制及创建/更新的不同空值语义见[公共网络说明](objects.md#网络设置)。

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "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
  }
}
```

:::::
:::::{tab-item} 字段说明

HTTP 200 的数据含义如下；示例值不是默认配置。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应说明。 |
| `data` | object | 创建返回的沙箱快照，不保证已就绪。 |

:::::
::::::
:::::::

## 结果确认

读取 data.id，继续[查询详情](get-sandbox.md)确认 phase。只有实际 ready 且目标操作成功，才可认定可用；创建 HTTP 200 也可能返回 provisioning、unknown 或 error。响应未知时先查原请求与已有对象，不盲目换名创建多个资源。

## 错误处理

按 HTTP 状态及响应 code 判断；[公共错误与恢复](objects.md#错误与恢复)区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源，也不能当成重试或清理已经完成。
