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

id

string

Managed sandbox ID for details, network, terminal, and deletion paths.

workspace_id

string

Owning workspace.

user_id

string

Creator user ID.

name

string

Display name:1–63 ASCII letters/digits and internal hyphens. Not a substitute for id.

phase

string

unknown, provisioning, ready, error, or deleting. Receiving a successful response does not mean ready.

edge_agent_id

string

Edge agent identity used by the service, not another freely selectable sandbox path ID.

network_mode

string

limited or unrestricted.

network_tools

string (array of strings)

Tool allowlist; may be omitted when empty. Interpret with network mode.

egress_endpoints

object (array of objects)

Additional egress host/port list; may be omitted when empty.

spec

string

small, medium, or large.

disk_gi

integer

Disk capacity in GiB.

compute_resource_id

string

Compute resource instance ID, returned when present; not a specification name.

created_at

string

Creation time in RFC 3339.

updated_at

string

Update time in RFC 3339.

update_available

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

host

string

Lowercase hostname without protocol, path, wildcard, credentials, port, or brackets. IP literals and localhost are invalid.

ports

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.

Last updated on