const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromSandbox: 'sbx_06d8k3m7q2v9x4b1n5c0e8f2ja',
freshSnapshot: true,
count: 10,
name: 'agent-42',
labels: {project: 'web', agent: 'reviewer'},
env: {NODE_ENV: 'production'},
files: [{path: '/home/user/.npmrc', content: '<string>', mode: '0644'}],
template: 'node-22-base',
stopAfterSeconds: 3600,
stopAt: '2026-11-16T12:00:00Z',
failFast: true
})
};
fetch('https://vms.dev/api/v1/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://vms.dev/api/v1/sandboxes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"freshSnapshot": true,
"count": 10,
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"env": {
"NODE_ENV": "production"
},
"files": [
{
"path": "/home/user/.npmrc",
"content": "<string>",
"mode": "0644"
}
],
"template": "node-22-base",
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"failFast": true
}
'import requests
url = "https://vms.dev/api/v1/sandboxes"
payload = {
"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"freshSnapshot": True,
"count": 10,
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"env": { "NODE_ENV": "production" },
"files": [
{
"path": "/home/user/.npmrc",
"content": "<string>",
"mode": "0644"
}
],
"template": "node-22-base",
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"failFast": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"name": "<string>",
"state": "creating",
"size": "small",
"health": "ok",
"errorReason": "host_lost",
"labels": {},
"ipv6": "2604:2dc0:100:32d5::1a",
"urls": [
{
"id": "url_06d8k3m7q2v9x4b1n5c0e8f2jb",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"port": 3000,
"url": "https://agent-42-3000-k3m7q2v9.vmsdev.run",
"public": true,
"token": "vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"sshHostKey": "<string>",
"sshUser": "agent-42-k3m7q2v9",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfterSeconds": 3600,
"dataExpiresAt": "2023-11-07T05:31:56Z",
"latestSnapshotAt": "2023-11-07T05:31:56Z",
"snapshotVerifiedAt": "2023-11-07T05:31:56Z",
"lastSnapshotLagSeconds": 4503599627370495,
"snapshotProgress": 0.5,
"hydrated": true,
"hydratedAt": "2023-11-07T05:31:56Z",
"hydration": {
"phase": "folding",
"filesDone": 4503599627370495,
"filesTotal": 4503599627370495,
"errorCode": "hydration_failed"
},
"lastReboot": {
"reason": "crash",
"at": "2023-11-07T05:31:56Z"
},
"operation": {
"id": "op_06d8k3m7q2v9x4b1n5c0e8f2ja",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"kind": "create",
"status": "pending",
"error": {
"code": "no_capacity",
"message": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
},
"forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"imageVersion": "ubuntu-26.04-20261116130819",
"pinImage": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"costMicros": 4503599627370495,
"batch": [
{
"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"name": "<string>",
"state": "creating",
"size": "small",
"health": "ok",
"errorReason": "host_lost",
"labels": {},
"ipv6": "2604:2dc0:100:32d5::1a",
"urls": [
{
"id": "url_06d8k3m7q2v9x4b1n5c0e8f2jb",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"port": 3000,
"url": "https://agent-42-3000-k3m7q2v9.vmsdev.run",
"public": true,
"token": "vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"sshHostKey": "<string>",
"sshUser": "agent-42-k3m7q2v9",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfterSeconds": 3600,
"dataExpiresAt": "2023-11-07T05:31:56Z",
"latestSnapshotAt": "2023-11-07T05:31:56Z",
"snapshotVerifiedAt": "2023-11-07T05:31:56Z",
"lastSnapshotLagSeconds": 4503599627370495,
"snapshotProgress": 0.5,
"hydrated": true,
"hydratedAt": "2023-11-07T05:31:56Z",
"hydration": {
"phase": "folding",
"filesDone": 4503599627370495,
"filesTotal": 4503599627370495,
"errorCode": "hydration_failed"
},
"lastReboot": {
"reason": "crash",
"at": "2023-11-07T05:31:56Z"
},
"operation": {
"id": "op_06d8k3m7q2v9x4b1n5c0e8f2ja",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"kind": "create",
"status": "pending",
"error": {
"code": "no_capacity",
"message": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
},
"forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"imageVersion": "ubuntu-26.04-20261116130819",
"pinImage": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"costMicros": 4503599627370495
}
]
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}Create a sandbox
Creates a sandbox of the size that you send. Send template to start the sandbox with the files of a template: its ID, its name, or a share code from another workspace. The sandbox takes a warm slot, or waits a few seconds for a new slot when a host has room, and moves through creating and starting to running. Read the sandbox or its operation to see when it is running. If no host has room, the API answers 503 with the code no_capacity at once. Send fromSandbox to fork a running or stopped sandbox: the fork gets the files and the environment variables of the source, and its own name, hostname, SSH host keys, IPv6 address, and agent key. It does not get the auto-stop time or the URLs of the source. Send count to make more than one fork. Needs the sandboxes:write scope.
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
fromSandbox: 'sbx_06d8k3m7q2v9x4b1n5c0e8f2ja',
freshSnapshot: true,
count: 10,
name: 'agent-42',
labels: {project: 'web', agent: 'reviewer'},
env: {NODE_ENV: 'production'},
files: [{path: '/home/user/.npmrc', content: '<string>', mode: '0644'}],
template: 'node-22-base',
stopAfterSeconds: 3600,
stopAt: '2026-11-16T12:00:00Z',
failFast: true
})
};
fetch('https://vms.dev/api/v1/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://vms.dev/api/v1/sandboxes \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"freshSnapshot": true,
"count": 10,
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"env": {
"NODE_ENV": "production"
},
"files": [
{
"path": "/home/user/.npmrc",
"content": "<string>",
"mode": "0644"
}
],
"template": "node-22-base",
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"failFast": true
}
'import requests
url = "https://vms.dev/api/v1/sandboxes"
payload = {
"fromSandbox": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"freshSnapshot": True,
"count": 10,
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"env": { "NODE_ENV": "production" },
"files": [
{
"path": "/home/user/.npmrc",
"content": "<string>",
"mode": "0644"
}
],
"template": "node-22-base",
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"failFast": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"name": "<string>",
"state": "creating",
"size": "small",
"health": "ok",
"errorReason": "host_lost",
"labels": {},
"ipv6": "2604:2dc0:100:32d5::1a",
"urls": [
{
"id": "url_06d8k3m7q2v9x4b1n5c0e8f2jb",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"port": 3000,
"url": "https://agent-42-3000-k3m7q2v9.vmsdev.run",
"public": true,
"token": "vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"sshHostKey": "<string>",
"sshUser": "agent-42-k3m7q2v9",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfterSeconds": 3600,
"dataExpiresAt": "2023-11-07T05:31:56Z",
"latestSnapshotAt": "2023-11-07T05:31:56Z",
"snapshotVerifiedAt": "2023-11-07T05:31:56Z",
"lastSnapshotLagSeconds": 4503599627370495,
"snapshotProgress": 0.5,
"hydrated": true,
"hydratedAt": "2023-11-07T05:31:56Z",
"hydration": {
"phase": "folding",
"filesDone": 4503599627370495,
"filesTotal": 4503599627370495,
"errorCode": "hydration_failed"
},
"lastReboot": {
"reason": "crash",
"at": "2023-11-07T05:31:56Z"
},
"operation": {
"id": "op_06d8k3m7q2v9x4b1n5c0e8f2ja",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"kind": "create",
"status": "pending",
"error": {
"code": "no_capacity",
"message": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
},
"forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"imageVersion": "ubuntu-26.04-20261116130819",
"pinImage": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"costMicros": 4503599627370495,
"batch": [
{
"id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"name": "<string>",
"state": "creating",
"size": "small",
"health": "ok",
"errorReason": "host_lost",
"labels": {},
"ipv6": "2604:2dc0:100:32d5::1a",
"urls": [
{
"id": "url_06d8k3m7q2v9x4b1n5c0e8f2jb",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"port": 3000,
"url": "https://agent-42-3000-k3m7q2v9.vmsdev.run",
"public": true,
"token": "vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
],
"sshHostKey": "<string>",
"sshUser": "agent-42-k3m7q2v9",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfterSeconds": 3600,
"dataExpiresAt": "2023-11-07T05:31:56Z",
"latestSnapshotAt": "2023-11-07T05:31:56Z",
"snapshotVerifiedAt": "2023-11-07T05:31:56Z",
"lastSnapshotLagSeconds": 4503599627370495,
"snapshotProgress": 0.5,
"hydrated": true,
"hydratedAt": "2023-11-07T05:31:56Z",
"hydration": {
"phase": "folding",
"filesDone": 4503599627370495,
"filesTotal": 4503599627370495,
"errorCode": "hydration_failed"
},
"lastReboot": {
"reason": "crash",
"at": "2023-11-07T05:31:56Z"
},
"operation": {
"id": "op_06d8k3m7q2v9x4b1n5c0e8f2ja",
"sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"kind": "create",
"status": "pending",
"error": {
"code": "no_capacity",
"message": "<string>"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"completedAt": "2023-11-07T05:31:56Z"
},
"forkedFrom": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
"imageVersion": "ubuntu-26.04-20261116130819",
"pinImage": true,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"costMicros": 4503599627370495
}
]
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}{
"error": {
"code": "no_capacity",
"message": "<string>",
"requestId": "<string>",
"retryAfterSeconds": 4503599627370495,
"sandboxId": "<string>"
}
}Authorizations
Headers
Body
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.
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.
^(?:(?:\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))$"2026-11-16T12:00:00Z"
Response
The new sandbox, with its create operation. With count, the first fork, and each fork in batch.
When the sandbox stops on its own. Null when auto-stop is off or the sandbox does not run.
^(?:(?:\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))$When the saved files are deleted: 30 days after a stop, or at a delete. Null while the sandbox runs.
^(?:(?:\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))$^(?:(?:\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))$^(?:(?:\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))$When the last restore put each saved file on the local disk. Null when the sandbox did not restore saved files.
^(?:(?:\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))$