Skip to main content
PATCH
Update a sandbox
Update a non-terminated sandbox’s proxy settings, automatic resume behavior, or egress network policy. Names are immutable: set name at creation. Sending name in a PATCH returns 400 Bad Request.

Control automatic resume

The optional boolean auto_resume controls whether proxy traffic wakes a suspended named sandbox: You can change this setting in any non-terminated state, including while suspended. Updating it neither suspends a running sandbox nor wakes a suspended one. Explicit resume still works and preserves the setting across later suspensions. This request disables automatic resume for an existing named sandbox:
The response includes the current auto_resume boolean. Setting auto_resume: false on an unnamed sandbox returns 400 Bad Request. Updating a terminated sandbox returns 409 Conflict.

Update other settings

Use exposed_ports and allow_unauthenticated_access to control proxy access. The network field is tri-state: omit it to leave the policy unchanged, send an object to replace it, or send null to clear it. See Networking. Send a resources resize in a separate PATCH. Combining it with any other field, including auto_resume, returns 400 Bad Request. Resource resizing requires a running sandbox; see Live resize.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sandbox_id
string
required

The ID of the sandbox.

Body

application/json
auto_resume
boolean

Omit to preserve the current setting. False prevents proxy traffic from waking a suspended named sandbox; proxied requests return 409 with code SANDBOX_AUTO_RESUME_DISABLED. True re-enables wake-on-traffic. Accepted in any non-terminated state, including suspended. Updating this flag neither suspends nor resumes the sandbox. False on an unnamed sandbox returns 400. Cannot be combined with resources.

allow_unauthenticated_access
boolean

Set or clear unauthenticated ingress routing for this sandbox.

exposed_ports
integer<int32>[]

Replace the exposed port allowlist. Pass an empty array to clear it and revert to the default management port only.

Required range: 1 <= x <= 65535
network
object

Update the sandbox egress network policy. This field is tri-state: omit it to leave the current policy unchanged, send an object to replace the whole policy, or send an explicit null to clear it (unrestricted egress). The change is applied to the live sandbox firewall as one atomic swap with no enforcement gap; already-established connections are not revoked. If a hostname in the new policy fails to resolve, the update is rejected and the previous policy stays enforced.

Response

Sandbox updated successfully

auto_resume
boolean
required

Whether proxy traffic may wake the sandbox while suspended. Defaults to true on creation. Explicit resume does not change this setting, and copies inherit it. Check status separately to determine whether the sandbox is currently suspended.

id
string
required
namespace
string
required
status
enum<string>
required
Available options:
pending,
running,
snapshotting,
suspending,
suspended,
terminated,
resume_failed
created_at
integer<int64>
required

Milliseconds since Unix epoch.

resources
object
required
timeout_secs
integer<int64>
required
allow_unauthenticated_access
boolean
required

Whether sandbox ingress may route requests without auth validation.

image
string
pending_reason
string | null

Present when status is pending.

outcome
string | null

Platform-specific termination outcome string returned for completed sandboxes.

termination_reason
string | null

Typed reason the sandbox terminated (e.g. FileSystemNotFound, FileSystemSnapshotNotFound, ImageNotFound, no_capacity when a max_pending_secs bound ran out while waiting for a host, cancelled when a pending sandbox was deleted). Present on failed terminations.

error_details
string | null

Optional diagnosis for termination or a recoverable resume failure. An accepted explicit resume clears the previous diagnosis. Inspect status rather than classifying failure from this text.

container_id
string | null
executor_id
string | null
ingress_endpoint
string | null

Canonical server-provided base for sandbox-specific ingress.

sandbox_url
string | null

Sandbox-specific management URL derived from ingress_endpoint.

pool_id
string | null
network_policy
null | object

Egress network policy currently applied to the sandbox. null when egress is unrestricted.

exposed_ports
integer<int32>[] | null

Additional routable ingress ports. When null, only the management port 9501 is routable.

Required range: 1 <= x <= 65535
template_id
string | null
name
string | null
file_systems
object[]

Filesystems currently mounted into the sandbox.

snapshot_id
string | null

Retained checkpoint ID. A recoverable resume failure preserves the original checkpoint for an explicit retry.