const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'agent-42',
labels: {project: 'web', agent: 'reviewer'},
stopAfterSeconds: 3600,
stopAt: '2026-11-16T12:00:00Z',
pinImage: true
})
};
fetch('https://vms.dev/api/v1/sandboxes/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request PATCH \
--url https://vms.dev/api/v1/sandboxes/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"pinImage": true
}
'import requests
url = "https://vms.dev/api/v1/sandboxes/{id}"
payload = {
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"pinImage": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(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
}{
"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>"
}
}Update a sandbox
Changes the name, the labels, or the state of a sandbox. The request changes only the fields that you send. The labels that you send replace all labels of the sandbox. Send name: null to remove the name.
Send state: stopped to stop a running sandbox. The sandbox moves to stopping: the API runs ~/.vms/pre-stop (at most 60 seconds), takes a last snapshot, and pauses the sandbox. Then the sandbox is stopped, and billing stops. For 10 minutes, the host keeps the memory of the sandbox. A stop while a stop is pending returns the pending operation. If the last snapshot fails 3 times, the operation is failing, the sandbox runs again and is not billed, and the stop tries again each 5 minutes. After 3 days, the stop uses the last good snapshot and sends an email to the owners and admins.
Send state: running within 10 minutes of a stop to resume the sandbox with its memory and its processes. A resume is a start, so the start limits of the plan apply. A resume while a stop is failing cancels the stop.
With state, the API answers 202 with the operation of the stop or the resume. Needs the sandboxes:write scope.
const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'agent-42',
labels: {project: 'web', agent: 'reviewer'},
stopAfterSeconds: 3600,
stopAt: '2026-11-16T12:00:00Z',
pinImage: true
})
};
fetch('https://vms.dev/api/v1/sandboxes/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request PATCH \
--url https://vms.dev/api/v1/sandboxes/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"pinImage": true
}
'import requests
url = "https://vms.dev/api/v1/sandboxes/{id}"
payload = {
"name": "agent-42",
"labels": {
"project": "web",
"agent": "reviewer"
},
"stopAfterSeconds": 3600,
"stopAt": "2026-11-16T12:00:00Z",
"pinImage": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(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
}{
"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
Body
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.
^(?:(?:\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 changed sandbox.
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))$