Skip to main content
POST
Create a sandbox

Authorizations

Authorization
string
header
required

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

Headers

idempotency-key
string

A unique value for each new sandbox, such as a UUID. A second request with the same key within 24 hours returns the first result.

Required string length: 1 - 255

Body

application/json
size
enum<string>

The size of the sandbox. Send it for each new sandbox. A fork without size has the size of its source.

Available options:
small,
medium,
large,
xlarge
fromSandbox
string

The ID of a running or stopped sandbox to fork. The fork gets the files and the environment variables of this sandbox, and a new name, hostname, SSH host keys, IPv6 address, and agent key.

Minimum string length: 1
Example:

"sbx_06d8k3m7q2v9x4b1n5c0e8f2ja"

freshSnapshot
boolean

Send it only with fromSandbox. When the source runs, true (the default) takes a new snapshot of the source first, so that the fork has the latest files. false starts the fork from the last snapshot of the source. A stopped source has no new files, so this field has no effect on it.

count
integer

Send it only with fromSandbox: the number of forks to make, 1 to 100. The answer is the first fork, with each fork in batch. If one fork cannot start, the API makes no fork. Do not send name with a count of more than 1.

Required range: 1 <= x <= 100
Example:

10

name
string

A name that is unique in the workspace: 1 to 63 lowercase letters, digits, and hyphens. It cannot start or end with a hyphen.

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

"agent-42"

labels
object

Up to 50 labels. A key has 1 to 63 letters, digits, and the characters . _ / -, and starts and ends with a letter or a digit. A value has up to 255 characters.

Example:
env
object

Environment variables for each command, shell, and SSH session of the sandbox: up to 100. A name has letters, digits, and _, and does not start with a digit. A value has up to 4096 characters. The API does not show the values again.

Example:
files
object[]

Files to write when the sandbox starts the first time: up to 20, with up to 65536 characters of content in total. The owner of a file in /home/user is user.

Maximum array length: 20
template
string

The ID or the name of a ready template, or a share code of a template of another workspace. The sandbox starts with the files of the template.

Minimum string length: 1
Example:

"node-22-base"

stopAfterSeconds
integer | null

The seconds that the sandbox runs after each start before it stops on its own: 60 to 2592000 (30 days). The default is 3600 (1 hour). 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 time when the sandbox stops on its own. It must be in the future. 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"

failFast
boolean

Answer within 1.5 seconds. If the API cannot answer in time, it answers 503 no_capacity.

Response

The new sandbox, with its create operation. With count, the first fork, and each fork in batch.

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
batch
object[]

Each sandbox of the request, in creation order: the first is this sandbox. Only in the answer of a create with count.