Replace a managed sandbox network allowlist¶
Replace the entire tool and explicit host/ports allowlists of a managed sandbox. unrestricted mode rejects this operation; network_mode is not changed.
PATCH https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/{id}/network
Before you call this API¶
Prepare a valid identity, configured administrator eligibility, and an accessible authentication workspace for the current environment. Workspace Owner privileges or Genesis taas:admin do not automatically grant this administrator role. The example uses a personal access token and exactly one X-Workspace-ID. See AI Studio.
Decoding {} or null can request clearing; do not use either for a read-only probe. unrestricted rejects this allowlist operation with SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE. The update changes the Provider before saving the override. Failures attempt to restore the previous policy, but restoration can also fail. Save the existing configuration first, then check both configuration and actual policy.
Request parameters¶
curl -X PATCH "https://api.moi.matrixorigin.cn/v5/admin/agent-sandboxes/sandbox-example/network" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $AUTH_WORKSPACE_ID" \
-H "Content-Type: application/json" \
--data '{"network_tools":["curl"],"egress_endpoints":[{"host":"example.com","ports":[443]}]}'
Parameter |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes in example |
Valid personal access token for a configured administrator in this environment. Confirm other regular authentication methods such as Bearer for the environment. |
|
string |
Yes |
Exactly one nonempty authentication workspace header; not a target filter or the target quota workspace. |
|
string |
Yes |
Sandbox ID in the path. |
|
string (array of strings) |
Complete target list |
git, pip, npm, go, cargo, curl. Duplicates are removed, unknown values rejected, and values are not automatically trimmed. Omitted/null/[] all mean an empty set. |
|
object (array of objects) |
Complete target list |
Up to 256 distinct hosts, with up to 16 distinct ports per host, from 1 to 65535. Omitted/null/[] clears explicit targets. |
|
string |
Yes for each item |
Canonical lowercase hostname without IP addresses, localhost, wildcards, scheme, path, or port. |
|
integer (array of integers) |
Yes for each item |
At least one port per item. Identical host/port entries are normalized and merged. |
Successful response¶
{
"code": "OK",
"msg": "OK",
"data": {
"workspace": {
"id": "target-workspace",
"owner_id": "owner-example"
},
"id": "sandbox-example",
"workspace_id": "target-workspace",
"user_id": "owner-example",
"name": "示例沙箱",
"phase": "ready",
"edge_agent_id": "sandbox-example",
"network_mode": "limited",
"network_tools": [
"curl"
],
"egress_endpoints": [
{
"host": "example.com",
"ports": [
443
]
}
],
"spec": "small",
"disk_gi": 10,
"created_at": "2026-11-12T06:00:00Z",
"updated_at": "2026-11-12T06:00:00Z",
"update_available": false
}
}
Field |
Type |
Description |
|---|---|---|
|
string |
OK on success. |
|
string |
OK on success. |
|
object |
Success data. |
|
object, optional |
Optional administrative projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed. |
|
string |
Object identifier; currently the remote resource name for a sandbox. |
|
string |
Resource-owning workspace, not the workspace in the authentication header. |
|
string |
User fact from remote resource labels. |
|
string |
Display name. |
|
string |
unknown, provisioning, ready, error, or deleting; not the complete IAM cleanup state. |
|
string |
Associated execution environment identifier. |
|
string |
Currently limited or unrestricted; may be empty when historical labels are missing. This update does not switch modes. |
|
string (array of strings), optional |
Tool egress allowlist; may be omitted when empty. |
|
object (array of objects), optional |
Explicit host/ports egress allowlist; may be omitted when empty. |
|
string |
Specification projection; may be empty for historical labels. Creation enums do not imply this field was historically required. |
|
integer |
Disk size in GiB; may be 0 if remote labels are missing or unparseable. This does not permit creation with 0. |
|
string, optional |
Optional associated compute resource ID. |
|
string |
Creation time in RFC3339. |
|
string |
Update time in RFC3339; not guaranteed suitable for concurrency version control. |
|
boolean / null |
boolean or null. null means current image comparison information is insufficient; do not treat it as false. |
See Common objects for all public fields of nested objects and separate omission and null rules.
Error response¶
{"code":"ErrParamInvalid","msg":"Bad Request"}
Field |
Type |
Description |
|---|---|---|
|
string |
Error code for the current stage. |
|
string |
Error text; service classifications are usually localized. |
HTTP / code |
Conditions and recovery |
|---|---|
400 / ErrParamInvalid |
Missing authentication workspace, request decoding or integer parsing failure, or invalid quota fields. |
400 / SANDBOX_INVALID_SPEC |
Service validation failed for the list window, network tools, or similar values. Despite SPEC in the name, this is not limited to creation specifications. |
403 / COMPUTE_RESOURCE_SPEC_FORBIDDEN |
The current principal is not a configured administrator or the identity does not match at the permission boundary. |
503 / COMPUTE_RESOURCE_SPEC_ADMIN_UNAVAILABLE |
Classified administrator directory or authorization facts unavailable. |
404 / SANDBOX_NOT_FOUND |
Not a managed resource, ephemeral/pool resource, missing resource, or a hidden creation/deletion stage. |
503 / SANDBOX_IAM_UNAVAILABLE or SANDBOX_NETWORK_STORAGE_UNAVAILABLE |
Lifecycle identity or network persistence dependency unavailable. |
500 / SANDBOX_ERROR or ErrServer |
Unclassified Provider or similar failure, or localization failure; do not report all such failures as 503. |
See Errors and recovery for recovery stages.