Create a workspace sandbox¶
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.
POST https://api.moi.matrixorigin.cn/v5/agent-sandboxes
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 explains identities, fields, and states. Replace example resource values with actual ones.
Request¶
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]}]}'
Fields |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
1–63 ASCII letters, digits, or internal hyphens. Starts/ends with a letter or digit; uppercase is supported. |
|
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. |
|
string |
No |
small, medium, or large; omitted/empty uses medium. |
|
integer |
No |
10–50 GiB; omitted/0 uses 10. |
|
string |
No |
limited or unrestricted; omitted/empty uses limited. |
|
string (array of strings) |
No |
Tool allowlist for limited mode. Omitted/empty array uses the six default tools. |
|
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 for default tools, endpoint limits, and different creation/update empty-value semantics.
Successful response¶
{
"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
}
}
Meaning of HTTP 200 data below. Example values are not default configuration.
Field |
Type |
Description |
|---|---|---|
|
string |
OK on success. |
|
string |
Response explanation. |
|
object |
Sandbox snapshot returned at creation; readiness is not guaranteed. |
Confirm the result¶
Read data.id and continue with Get details 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.
Error handling¶
Check HTTP status and response code. Shared errors and recovery distinguishes parameter, permission, quota, provider, and unknown-result cases. Errors do not prove that no resource was created or that retry/cleanup completed.