<span id="更新沙箱出站允许列表"></span>

# Update sandbox egress allowlists

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

Replace a limited sandbox's tool and extra egress endpoint allowlists. This changes subsequent network access. Include every list entry you want to retain.

```text
PATCH https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/network
```

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

## Before you call this API

Prepare a personal access token and operation permissions for the target workspace. Keep environment, token, workspace, and sandbox ID consistent. [Common objects and result confirmation](objects.md) describes resource identity, fields, and states. Replace example resource values with actual values.

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

## Request

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

```bash
curl -X PATCH "https://api.moi.matrixorigin.cn/v5/agent-sandboxes/$SANDBOX_ID/network" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{"network_tools":["git"],"egress_endpoints":[{"host":"example.com","ports":[443]}]}'
```

:::::
:::::{tab-item} Parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sandbox_id` | string | Required in path | Target limited sandbox ID. |
| `network_tools` | string (array of strings) | No | Complete desired tool list. Omission/null/[] all clear this list. |
| `egress_endpoints` | object (array of objects) | No | Complete desired extra endpoint list. Omission/null/[] all clear it. |

This PATCH replaces both MOI-managed lists rather than updating only supplied fields. Unlike creation, where empty tools use defaults, omitting a list here clears it. These fields do not remove default control channels or independently managed rules. No updatable network_mode field exists, and unrestricted cannot become limited through this request. Allowlist updates for unrestricted sandboxes are rejected. See [common network information](objects.md#网络设置) for scope and format.

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

<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": "ready",
    "edge_agent_id": "sbx-example",
    "network_mode": "limited",
    "network_tools": [
      "git"
    ],
    "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

HTTP 200 data has the following meaning; example values are not defaults.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response description. |
| `data` | object | Updated sandbox and lists. |

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

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

## Confirm the result

Check policy against the returned values and details, and verify actual target access if needed. The service attempts to restore the original policy on failure, but an error does not guarantee restoration. Save original settings for verification.

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

## Error handling

Use HTTP status and response code. [Common errors and recovery](objects.md#错误与恢复) distinguishes parameters, permissions, quotas, providers, and unknown outcomes. An error does not prove no resource was created or that retries/cleanup have completed.
