Sandbox objects, networks, and result confirmation¶
Managed sandboxes belong to workspaces. Obtain an actual ID from current lists/creation, read its phase, then use the target capability. Runtime ephemeral sandboxes and cross-workspace administrator views have separate identities/scopes.
Sandbox fields¶
Field |
Type |
Description |
|---|---|---|
|
string |
Managed sandbox ID for details, network, terminal, and deletion paths. |
|
string |
Owning workspace. |
|
string |
Creator user ID. |
|
string |
Display name:1–63 ASCII letters/digits and internal hyphens. Not a substitute for id. |
|
string |
unknown, provisioning, ready, error, or deleting. Receiving a successful response does not mean ready. |
|
string |
Edge agent identity used by the service, not another freely selectable sandbox path ID. |
|
string |
limited or unrestricted. |
|
string (array of strings) |
Tool allowlist; may be omitted when empty. Interpret with network mode. |
|
object (array of objects) |
Additional egress host/port list; may be omitted when empty. |
|
string |
small, medium, or large. |
|
integer |
Disk capacity in GiB. |
|
string |
Compute resource instance ID, returned when present; not a specification name. |
|
string |
Creation time in RFC 3339. |
|
string |
Update time in RFC 3339. |
|
boolean or null |
true/false when the provider can determine it, otherwise null. Do not interpret unknown as false. |
Workspace lists apply current authorization and are not global audits. Conversation ephemeral runtime resources are excluded. Incomplete creation registration and deleting objects may also be hidden from lists/details. Visible counts can differ from quota occupancy.
Network settings¶
limited tool values are git, pip, npm, go, cargo, and curl. Duplicates are removed. Omitted/empty tool arrays at creation use these six defaults. During updates, both lists fully replace targets; omitted/null/[] clears the corresponding MOI-managed list rather than retaining old values.
Endpoint field |
Type |
Description |
|---|---|---|
|
string |
Lowercase hostname without protocol, path, wildcard, credentials, port, or brackets. IP literals and localhost are invalid. |
|
integer (array of integers) |
At least one port from 1 to 65535 is required. |
Up to 256 distinct hosts and16 distinct ports per host. Ports for the same host merge and deduplicate. URLs or host:443 cannot replace separate host/ports fields. Additional lists do not remove public control channels or independent provider rules.
Creating unrestricted requires deployment support and nonempty allowlists cannot be provided. Only with explicit include_network_capabilities=true does quota GET return unrestricted_network_allowed. Missing fields in older shapes mean neither false nor true. Network PATCH replaces limited allowlists only; it cannot switch modes or edit unrestricted.
Lifecycle and side effects¶
Creation allocates runtime resources and requires quota, privileges, and deployment enablement. With compute binding enabled, it also needs a bindable same-workspace resource instance or resolvable default configuration. Responses may still show provisioning/unknown/error. Read actual subsequent state and verify the intended operation.
Quota settings allow explicit0; omitted fields retain values. Lower limits do not automatically delete existing objects. Occupancy includes remote resources and unfinished durable allocations; visible list length is not a substitute.
Failed network writes attempt to restore old policies, but restoration may fail. Failed deletion may already have entered a hidden stage. Detail404 or absence in lists establishes query invisibility only, not complete cleanup of remote execution, credentials, metering, and ownership. Retain original IDs/request identifiers and read again before recovery decisions.
Terminal and SSH¶
Short-lived terminal tokens and SSH sessions are different objects. Terminal tokens currently expire60 seconds after issuance. Established WebSocket sessions last at most30 minutes and recheck current role/resource privileges roughly every 30 seconds. Token expiry does not define the established session’s duration, and original role authorization is not permanent.
SSH returns provider gateway information and millisecond expiration. Successful requests do not establish a connection; a compatible client handles the gateway protocol. Neither short-lived credential may appear as a real value in public examples, review Traces, or shared logs.
Errors and recovery¶
HTTP/code |
Meaning |
Handling |
|---|---|---|
401 / ErrUnauthorized |
Identity or terminal-token authentication failed. |
Check current-environment credentials without substituting another environment’s resources. |
403 / SANDBOX_FORBIDDEN |
Current sandbox operation denied. |
Check target workspace, resource, and current role. |
404 / SANDBOX_NOT_FOUND |
Resource absent or invisible in its current lifecycle. |
Check original creation/deletion records;404 does not prove complete cleanup. |
400 / SANDBOX_INVALID_NAME, SANDBOX_INVALID_SPEC, or SANDBOX_EGRESS_* |
Name, specification/network, or endpoint validation failed. |
Correct the specific field and limits. Different invalid inputs need not share one code. |
400 / SANDBOX_NETWORK_UNRESTRICTED_DISABLED |
Deployment disallows unrestricted creation. |
Explicitly read network capabilities and choose an allowed mode. |
400 / SANDBOX_NETWORK_ALLOWLIST_UNAVAILABLE |
unrestricted rejects allowlist updates. |
Do not use this endpoint to switch network modes. |
409 / SANDBOX_QUOTA_EXCEEDED |
Allocation reached admission quota. |
Read actual occupancy; adjust configuration with appropriate privileges or clean up confirmed idle resources. |
409 / SANDBOX_REQUEST_CONFLICT |
Same request identity with different creation input. |
Retain original identity/input and read again. Do not blindly reuse it for another creation. |
409 / SANDBOX_MANUAL_RECOVERY_REQUIRED, SANDBOX_WORKSPACE_DELETING |
Recovery required or workspace deleting. |
Retain object/request identity and await recovery or contact an administrator. |
503 / SANDBOX_IAM_UNAVAILABLE, SANDBOX_NETWORK_STORAGE_UNAVAILABLE |
Authorization or policy storage temporarily unavailable. |
Retain request/original policy and confirm actual state before proceeding. |
501 / SANDBOX_TERMINAL_NOT_CONFIGURED |
Terminal signing service unconfigured. |
Check deployment configuration. Registered routes do not prove availability. |
500 / SANDBOX_ERROR |
Other current service error. |
Retain sanitized request identifiers and investigate. Errors do not imply no side effects. |
Complete error responses usually contain {code,msg}. After terminal upgrade, errors use WebSocket messages rather than regular HTTP JSON; see Terminal protocol.