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

X-API-Key

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.

X-Workspace-ID

string

Yes

Exactly one nonempty authentication workspace header; not a target filter or the target quota workspace.

id

string

Yes

Sandbox ID in the path.

network_tools

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.

egress_endpoints

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.

egress_endpoints[].host

string

Yes for each item

Canonical lowercase hostname without IP addresses, localhost, wildcards, scheme, path, or port.

egress_endpoints[].ports

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

code

string

OK on success.

msg

string

OK on success.

data

object

Success data.

data.workspace

object, optional

Optional administrative projection. The current Provider supplies at least ID/owner_id; names and account names are not guaranteed.

data.id

string

Object identifier; currently the remote resource name for a sandbox.

data.workspace_id

string

Resource-owning workspace, not the workspace in the authentication header.

data.user_id

string

User fact from remote resource labels.

data.name

string

Display name.

data.phase

string

unknown, provisioning, ready, error, or deleting; not the complete IAM cleanup state.

data.edge_agent_id

string

Associated execution environment identifier.

data.network_mode

string

Currently limited or unrestricted; may be empty when historical labels are missing. This update does not switch modes.

data.network_tools

string (array of strings), optional

Tool egress allowlist; may be omitted when empty.

data.egress_endpoints

object (array of objects), optional

Explicit host/ports egress allowlist; may be omitted when empty.

data.spec

string

Specification projection; may be empty for historical labels. Creation enums do not imply this field was historically required.

data.disk_gi

integer

Disk size in GiB; may be 0 if remote labels are missing or unparseable. This does not permit creation with 0.

data.compute_resource_id

string, optional

Optional associated compute resource ID.

data.created_at

string

Creation time in RFC3339.

data.updated_at

string

Update time in RFC3339; not guaranteed suitable for concurrency version control.

data.update_available

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

code

string

Error code for the current stage.

msg

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.

Last updated on