Skip to main content
PATCH
Update a sandbox

Authorizations

Authorization
string
header
required

An API key that starts with vms_. Make one in Settings > API keys.

Path Parameters

id
string
required
Example:

"sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"

Body

application/json
name
string | null

The new name. Send null to remove the name.

Pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
Example:

"agent-42"

labels
object

The new labels. They replace all labels of the sandbox.

Example:
stopAfterSeconds
integer | null

The new seconds that the sandbox runs after each start, counted from the current start. If this time is already past, the sandbox stops now. Send null to turn off auto-stop. Do not send it with stopAt.

Required range: 60 <= x <= 2592000
Example:

3600

stopAt
string<date-time> | null

The new time when the sandbox stops on its own. It must be in the future, and the sandbox must be creating, starting, or running. Send null to turn off auto-stop. Do not send it with stopAfterSeconds.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Example:

"2026-11-16T12:00:00Z"

state
enum<string>

Send stopped to stop the sandbox, or running to resume it. The response is 202 with the operation of the stop or the resume.

Available options:
stopped,
running
size
enum<string>

The size after the resume. Send it only with state running, to a stopped sandbox.

Available options:
small,
medium,
large,
xlarge
pinImage
boolean

Send true to keep the current base image at each resume. Send false to move the sandbox to the latest base image at the next resume after the 10-minute hold.

Response

The changed sandbox.

id
string
required
Example:

"sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"

name
string | null
required
state
enum<string>
required
Available options:
creating,
starting,
running,
stopping,
stopped,
error,
deleting,
deleted,
failed
size
enum<string>
required

The vCPU, RAM, and disk of a sandbox.

Available options:
small,
medium,
large,
xlarge
health
enum<string> | null
required

Null when the sandbox is not running.

Available options:
ok,
degraded,
unreachable
errorReason
enum<string> | null
required

Why the sandbox is in the error state.

Available options:
host_lost,
boot_failed,
restore_failed
labels
object
required
ipv6
string | null
required
Example:

"2604:2dc0:100:32d5::1a"

urls
object[]
required
sshHostKey
string | null
required

The public SSH host key of the sandbox.

sshUser
string
required

The user name for ssh.vms.dev: the name and the workspace code, or the sandbox ID when the sandbox has no name.

Example:

"agent-42-k3m7q2v9"

stopAt
string<date-time> | null
required

When the sandbox stops on its own. Null when auto-stop is off or the sandbox does not run.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
stopAfterSeconds
integer | null
required

The seconds that the sandbox runs after each start before it stops on its own. Null when auto-stop is off.

Required range: 0 < x <= 9007199254740991
Example:

3600

dataExpiresAt
string<date-time> | null
required

When the saved files are deleted: 30 days after a stop, or at a delete. Null while the sandbox runs.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
latestSnapshotAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
snapshotVerifiedAt
string<date-time> | null
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
lastSnapshotLagSeconds
integer | null
required
Required range: 0 <= x <= 9007199254740991
snapshotProgress
number | null
required

The part of the current snapshot that is done, 0 to 1.

Required range: 0 <= x <= 1
hydrated
boolean
required

true when each saved file is on the local disk. After a resume from saved files, the sandbox is running before this is true: a file that is not local yet downloads when a program opens it.

hydratedAt
string<date-time> | null
required

When the last restore put each saved file on the local disk. Null when the sandbox did not restore saved files.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
hydration
object
required

The progress of the last restore of saved files.

lastReboot
object | null
required
operation
object | null
required

The latest operation on the sandbox.

forkedFrom
string | null
required

The ID of the sandbox that this sandbox is a fork of. Null when it is not a fork.

Example:

"sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"

imageVersion
string | null
required

The version of the base image of the sandbox. Null before the first start.

Example:

"ubuntu-26.04-20261116130819"

pinImage
boolean
required

true when a resume keeps the current base image. false when a resume after the 10-minute hold moves the sandbox to the latest base image.

createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
updatedAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
costMicros
integer

The cost of the sandbox in the current month (UTC), in micro-dollars: 1,000,000 is $1. Only in a list with include=cost.

Required range: 0 <= x <= 9007199254740991