<span id="创建工作区沙箱"></span>

# Create a workspace sandbox

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

Create a managed sandbox with specification, disk, and network settings. This allocates runtime resources. Check quota first and retain the sandbox ID for subsequent reads and cleanup.

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

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token and the required privileges for the target workspace. Keep environment, token, workspace, and sandbox ID consistent. [Common objects and result confirmation](objects.md) explains identities, fields, and states. Replace example resource values with actual ones.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1–63 ASCII letters, digits, or internal hyphens. Starts/ends with a letter or digit; uppercase is supported. |
| `compute_resource_id` | string | Conditional | Existing bindable compute resource ID. Required if compute binding is enabled without a resolvable default resource. Use an instance ID, not a specification ID. |
| `spec` | string | No | small, medium, or large; omitted/empty uses medium. |
| `disk_gi` | integer | No | 10–50 GiB; omitted/0 uses 10. |
| `network_mode` | string | No | limited or unrestricted; omitted/empty uses limited. |
| `network_tools` | string (array of strings) | No | Tool allowlist for limited mode. Omitted/empty array uses the six default tools. |
| `egress_endpoints` | object (array of objects) | No | Additional host/port allowlist for limited mode; see common network objects. |

unrestricted requires explicit deployment support and disallows nonempty tool/endpoint lists. Explicitly request network capabilities through quota; missing fields do not establish permission. See [Common network information](objects.md#网络设置) for default tools, endpoint limits, and different creation/update empty-value semantics.

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

Meaning of HTTP 200 data below. Example values are not default configuration.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response explanation. |
| `data` | object | Sandbox snapshot returned at creation; readiness is not guaranteed. |

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

<span id="结果确认"></span>

## Confirm the result

Read data.id and continue with [Get details](get-sandbox.md) to confirm phase. Only actual ready state and a successful target operation establish usability. Creation HTTP 200 may still return provisioning, unknown, or error. When a response is unknown, check the original request and existing objects rather than blindly creating several resources under new names.

<span id="错误处理"></span>

## Error handling

Check HTTP status and response code. [Shared errors and recovery](objects.md#错误与恢复) distinguishes parameter, permission, quota, provider, and unknown-result cases. Errors do not prove that no resource was created or that retry/cleanup completed.
