curl --request PATCH \
--url https://api.instabox.sh/v1/machines/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"maxRunMinutes": 1073741823,
"name": "<string>",
"rootDiskGiB": 512,
"vcpus": 16,
"memMiB": 65536,
"persistentDiskGiB": 512,
"metadata": {},
"autoSuspendAfterSeconds": 123,
"vault": true,
"apply": "restart"
}
'import requests
url = "https://api.instabox.sh/v1/machines/{id}"
payload = {
"maxRunMinutes": 1073741823,
"name": "<string>",
"rootDiskGiB": 512,
"vcpus": 16,
"memMiB": 65536,
"persistentDiskGiB": 512,
"metadata": {},
"autoSuspendAfterSeconds": 123,
"vault": True,
"apply": "restart"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
maxRunMinutes: 1073741823,
name: '<string>',
rootDiskGiB: 512,
vcpus: 16,
memMiB: 65536,
persistentDiskGiB: 512,
metadata: {},
autoSuspendAfterSeconds: 123,
vault: true,
apply: 'restart'
})
};
fetch('https://api.instabox.sh/v1/machines/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'maxRunMinutes' => 1073741823,
'name' => '<string>',
'rootDiskGiB' => 512,
'vcpus' => 16,
'memMiB' => 65536,
'persistentDiskGiB' => 512,
'metadata' => [
],
'autoSuspendAfterSeconds' => 123,
'vault' => true,
'apply' => 'restart'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instabox.sh/v1/machines/{id}"
payload := strings.NewReader("{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.instabox.sh/v1/machines/{id}")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instabox.sh/v1/machines/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"desiredState": "creating",
"state": "creating",
"revision": 123,
"operationId": "<string>",
"template": {
"id": "<string>",
"version": "<string>",
"digest": "<string>",
"kernel": "<string>"
},
"spec": {
"vcpus": 123,
"memMiB": 123,
"persistentDiskGiB": 123,
"rootDiskGiB": 123
},
"storage": {
"sizeGiB": 123,
"mountPath": "/data",
"persistent": true,
"synced": true,
"snapshotSeq": 123
},
"runtime": {
"ready": true,
"processesPreserved": true
},
"autoSuspendAfterSeconds": 123,
"maxRunMinutes": 1073741823,
"runStartedAt": "2023-11-07T05:31:56Z",
"cooldownUntil": "2023-11-07T05:31:56Z",
"metadata": {},
"vault": true,
"guestUser": "alice",
"orgId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"snapshot": {
"id": "<string>"
},
"image": {
"id": "<string>"
},
"lastError": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"archiveAt": "2023-11-07T05:31:56Z",
"deleteAt": "2023-11-07T05:31:56Z",
"readyAt": "2023-11-07T05:31:56Z",
"cooldownReason": "abuse_egress_blocklist",
"abuseLock": {
"at": "2023-11-07T05:31:56Z",
"explanation": "<string>",
"what": "<string>",
"appeal": "<string>",
"dst": "<string>",
"port": 123,
"kind": "<string>",
"count": 123,
"coreShare": 123,
"process": "<string>",
"pool": "<string>"
},
"autoSuspendedAt": "2023-11-07T05:31:56Z",
"envNames": [
"<string>"
],
"free": true,
"earlyAllowanceEnded": true,
"oomKills": 123,
"lastOom": {
"at": "2023-11-07T05:31:56Z",
"pid": 123,
"process": "<string>",
"rssBytes": 123,
"anonRssBytes": 123,
"cgroup": true,
"uid": 123
}
}{
"id": "<string>",
"machineId": "<string>",
"type": "create",
"state": "queued",
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"phase": "<string>",
"forkInherited": true,
"trigger": "idle",
"machine": {
"id": "<string>",
"name": "<string>",
"desiredState": "creating",
"state": "creating",
"revision": 123,
"operationId": "<string>",
"template": {
"id": "<string>",
"version": "<string>",
"digest": "<string>",
"kernel": "<string>"
},
"spec": {
"vcpus": 123,
"memMiB": 123,
"persistentDiskGiB": 123,
"rootDiskGiB": 123
},
"storage": {
"sizeGiB": 123,
"mountPath": "/data",
"persistent": true,
"synced": true,
"snapshotSeq": 123
},
"runtime": {
"ready": true,
"processesPreserved": true
},
"autoSuspendAfterSeconds": 123,
"maxRunMinutes": 1073741823,
"runStartedAt": "2023-11-07T05:31:56Z",
"cooldownUntil": "2023-11-07T05:31:56Z",
"metadata": {},
"vault": true,
"guestUser": "alice",
"orgId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"snapshot": {
"id": "<string>"
},
"image": {
"id": "<string>"
},
"lastError": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"archiveAt": "2023-11-07T05:31:56Z",
"deleteAt": "2023-11-07T05:31:56Z",
"readyAt": "2023-11-07T05:31:56Z",
"cooldownReason": "abuse_egress_blocklist",
"abuseLock": {
"at": "2023-11-07T05:31:56Z",
"explanation": "<string>",
"what": "<string>",
"appeal": "<string>",
"dst": "<string>",
"port": 123,
"kind": "<string>",
"count": 123,
"coreShare": 123,
"process": "<string>",
"pool": "<string>"
},
"autoSuspendedAt": "2023-11-07T05:31:56Z",
"envNames": [
"<string>"
],
"free": true,
"earlyAllowanceEnded": true,
"oomKills": 123,
"lastOom": {
"at": "2023-11-07T05:31:56Z",
"pid": 123,
"process": "<string>",
"rssBytes": 123,
"anonRssBytes": 123,
"cgroup": true,
"uid": 123
}
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}Rename, resize (vCPUs, memory, disk) a stopped sandbox, or set its idle pause and metadata.
Synchronous. Absent fields are unchanged. autoSuspendAfterSeconds and metadata apply in any state, also while an operation runs, and do not change revision: metadata replaces the metadata ({} clears it).
name renames the sandbox in any state, also while an operation runs. Its ID, public port URLs and SSH certificates stay the same; the old name stops resolving at once. A name another live sandbox of the org has is 409 operation_conflict. The guest hostname (instabox-<name>) follows at the sandbox’s next start or resume, ~/MACHINE.md at its next start from stopped.
Resizing (persistentDiskGiB) grows a paid sandbox’s disk (/data) up to the plan’s maxDiskGiB (pro 200, builder 500, team and enterprise 1024) and the stored-data limit, and the org must be under that limit (429 quota_exceeded). A free sandbox’s size is fixed (400 spec_not_allowed). An admin can override that per user (diskResize) and, from a signed-in session, grow any sandbox without the limit. Each size is 1-1024 GiB (more is 400 bad_request), and needs no operation in progress (else 409 operation_conflict). The disk (/data) of a running sandbox grows online: no restart, files and processes stay; when it can’t (rare: the sandbox is unreachable or its host is older) it is 409 grow_needs_stop: stop it and send the size again. A stopped sandbox’s disk grows at its next start. It shrinks only while stopped (else 409 operation_conflict) and only when the used data plus 10% (at least 1 GiB) fits (else 409 disk_too_small, nothing changes); the shrink applies at the next start, which keeps the larger size if the data has grown past it by then. The system disk (rootDiskGiB, admins) only grows (a smaller size is 400 bad_request), and only while stopped. Growing either disk needs a template with the root-grow capability (else 400 bad_request); a shrink does not. At create the disks come with the size; this is the way to get bigger ones.
vcpus and memMiB change a paid sandbox’s size to another of its workspace’s sizes (allowedSpecs of GET /v1/orgs/{id}), named as at create: one field picks the one size that matches it, else name both. The sandbox must be stopped with no operation in progress (else 409 operation_conflict); the new size applies at its next start, which boots it fresh (files stay), and running time is rated at the new size from then on. That start’s operation fails, and the sandbox stays stopped at its new size, when its host has no room for the new size (no_capacity) or runs an older node-agent that cannot resize (host_unavailable), both retryable; resize it back or start it later. A size the plan does not offer and the free sandbox are 400 spec_not_allowed in any state (checked before the 409); the same size changes nothing. Admins may give any size within the API’s ranges. As at create, a field it does not know is 400 unknown_field and nothing changes, so diskGiB here is refused.
apply: "restart" lets a running or paused sandbox take a change that needs a stop (vcpus/memMiB, a /data shrink, a system-disk grow, or a grow it can’t do online) instead of the 409: the reply is 202 with one resize operation, under this request’s idempotency key, that stops it (resuming a paused one first; its running processes end), applies the size and starts it again (phases stopping, resizing, booting). The server finishes it even if the caller goes away, so a sandbox can resize itself. When it can’t start at the new size, it starts again at the old one and the operation fails with the reason. A change it can take as it is (a stopped sandbox, an online grow) is the usual 200. GET /v1/me resizeRestart says the server takes it; a server that does not yet answers 400 resize_restart_off. It is checked against the settings this request leaves: maxRunMinutes: 0 with it is 400 max_run_disabled (resize, then set it). The operation boots under the max-run it was accepted with. API keys: needs one of the scopes machines:write.
curl --request PATCH \
--url https://api.instabox.sh/v1/machines/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"maxRunMinutes": 1073741823,
"name": "<string>",
"rootDiskGiB": 512,
"vcpus": 16,
"memMiB": 65536,
"persistentDiskGiB": 512,
"metadata": {},
"autoSuspendAfterSeconds": 123,
"vault": true,
"apply": "restart"
}
'import requests
url = "https://api.instabox.sh/v1/machines/{id}"
payload = {
"maxRunMinutes": 1073741823,
"name": "<string>",
"rootDiskGiB": 512,
"vcpus": 16,
"memMiB": 65536,
"persistentDiskGiB": 512,
"metadata": {},
"autoSuspendAfterSeconds": 123,
"vault": True,
"apply": "restart"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
maxRunMinutes: 1073741823,
name: '<string>',
rootDiskGiB: 512,
vcpus: 16,
memMiB: 65536,
persistentDiskGiB: 512,
metadata: {},
autoSuspendAfterSeconds: 123,
vault: true,
apply: 'restart'
})
};
fetch('https://api.instabox.sh/v1/machines/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.instabox.sh/v1/machines/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'maxRunMinutes' => 1073741823,
'name' => '<string>',
'rootDiskGiB' => 512,
'vcpus' => 16,
'memMiB' => 65536,
'persistentDiskGiB' => 512,
'metadata' => [
],
'autoSuspendAfterSeconds' => 123,
'vault' => true,
'apply' => 'restart'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.instabox.sh/v1/machines/{id}"
payload := strings.NewReader("{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.instabox.sh/v1/machines/{id}")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.instabox.sh/v1/machines/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"maxRunMinutes\": 1073741823,\n \"name\": \"<string>\",\n \"rootDiskGiB\": 512,\n \"vcpus\": 16,\n \"memMiB\": 65536,\n \"persistentDiskGiB\": 512,\n \"metadata\": {},\n \"autoSuspendAfterSeconds\": 123,\n \"vault\": true,\n \"apply\": \"restart\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"desiredState": "creating",
"state": "creating",
"revision": 123,
"operationId": "<string>",
"template": {
"id": "<string>",
"version": "<string>",
"digest": "<string>",
"kernel": "<string>"
},
"spec": {
"vcpus": 123,
"memMiB": 123,
"persistentDiskGiB": 123,
"rootDiskGiB": 123
},
"storage": {
"sizeGiB": 123,
"mountPath": "/data",
"persistent": true,
"synced": true,
"snapshotSeq": 123
},
"runtime": {
"ready": true,
"processesPreserved": true
},
"autoSuspendAfterSeconds": 123,
"maxRunMinutes": 1073741823,
"runStartedAt": "2023-11-07T05:31:56Z",
"cooldownUntil": "2023-11-07T05:31:56Z",
"metadata": {},
"vault": true,
"guestUser": "alice",
"orgId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"snapshot": {
"id": "<string>"
},
"image": {
"id": "<string>"
},
"lastError": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"archiveAt": "2023-11-07T05:31:56Z",
"deleteAt": "2023-11-07T05:31:56Z",
"readyAt": "2023-11-07T05:31:56Z",
"cooldownReason": "abuse_egress_blocklist",
"abuseLock": {
"at": "2023-11-07T05:31:56Z",
"explanation": "<string>",
"what": "<string>",
"appeal": "<string>",
"dst": "<string>",
"port": 123,
"kind": "<string>",
"count": 123,
"coreShare": 123,
"process": "<string>",
"pool": "<string>"
},
"autoSuspendedAt": "2023-11-07T05:31:56Z",
"envNames": [
"<string>"
],
"free": true,
"earlyAllowanceEnded": true,
"oomKills": 123,
"lastOom": {
"at": "2023-11-07T05:31:56Z",
"pid": 123,
"process": "<string>",
"rssBytes": 123,
"anonRssBytes": 123,
"cgroup": true,
"uid": 123
}
}{
"id": "<string>",
"machineId": "<string>",
"type": "create",
"state": "queued",
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"phase": "<string>",
"forkInherited": true,
"trigger": "idle",
"machine": {
"id": "<string>",
"name": "<string>",
"desiredState": "creating",
"state": "creating",
"revision": 123,
"operationId": "<string>",
"template": {
"id": "<string>",
"version": "<string>",
"digest": "<string>",
"kernel": "<string>"
},
"spec": {
"vcpus": 123,
"memMiB": 123,
"persistentDiskGiB": 123,
"rootDiskGiB": 123
},
"storage": {
"sizeGiB": 123,
"mountPath": "/data",
"persistent": true,
"synced": true,
"snapshotSeq": 123
},
"runtime": {
"ready": true,
"processesPreserved": true
},
"autoSuspendAfterSeconds": 123,
"maxRunMinutes": 1073741823,
"runStartedAt": "2023-11-07T05:31:56Z",
"cooldownUntil": "2023-11-07T05:31:56Z",
"metadata": {},
"vault": true,
"guestUser": "alice",
"orgId": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"snapshot": {
"id": "<string>"
},
"image": {
"id": "<string>"
},
"lastError": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
},
"archiveAt": "2023-11-07T05:31:56Z",
"deleteAt": "2023-11-07T05:31:56Z",
"readyAt": "2023-11-07T05:31:56Z",
"cooldownReason": "abuse_egress_blocklist",
"abuseLock": {
"at": "2023-11-07T05:31:56Z",
"explanation": "<string>",
"what": "<string>",
"appeal": "<string>",
"dst": "<string>",
"port": 123,
"kind": "<string>",
"count": 123,
"coreShare": 123,
"process": "<string>",
"pool": "<string>"
},
"autoSuspendedAt": "2023-11-07T05:31:56Z",
"envNames": [
"<string>"
],
"free": true,
"earlyAllowanceEnded": true,
"oomKills": 123,
"lastOom": {
"at": "2023-11-07T05:31:56Z",
"pid": 123,
"process": "<string>",
"rssBytes": 123,
"anonRssBytes": 123,
"cgroup": true,
"uid": 123
}
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "unauthenticated",
"message": "<string>",
"requestId": "<string>",
"retryable": true,
"operationId": "<string>",
"reason": "missing_key",
"hint": "<string>",
"docs": "<string>",
"docs_url": "<string>",
"requiredScopes": [
"<string>"
],
"retryAfterSeconds": 2,
"at": "2023-11-07T05:31:56Z"
}
}Authorizations
Opaque instabox access token (1 hour). Refresh with /v1/auth/refresh (refresh token valid 30 days, rotates on use).
Headers
Client-generated key, 1-200 printable ASCII characters, scoped to the
user. Same key and same method+path+body returns the original response;
same key with a different request returns 409 idempotency_conflict.
Records are kept for 7 days.
1 - 200^[\x21-\x7e]+$Path Parameters
Sandbox ID (m_ + 26 lowercase base32 characters).
^m_[a-z2-7]{26}$Body
A body key that is none of these is refused with 400 unknown_field (keys match case-insensitively). The retired lifetime timeout (timeoutSeconds, onTimeout or timeout, any value but null) is 400 unknown_field naming maxRunMinutes and autoSuspendAfterSeconds instead (to an instabox-cli/<version> User-Agent, that the CLI is out of date and the commands instabox max-run, auto-suspend and rm), and nothing changes.
Maximum continuous runtime in minutes. -1 is unlimited; 0 sleeps immediately. Independent of idle auto-pause; whichever condition is reached first pauses the sandbox. Free machines default to 480 and only an admin session can change them. The service manages free runtime and may pause a run earlier. The response reports the current limit from runStartedAt; it can change during the run. Paid machines default to -1 and their users can change this setting. Max-run suspension starts a cooldown, returning 409 machine_cooldown with Retry-After on every wake path. By default it is 5 to 20 minutes (5 plus a random 0 to 15) on a paid plan and for the first such pause in a row on the free plan. Back-to-back pauses on the free plan rest longer (60 to 75, then 120 to 135 minutes): "Longer cooldowns on the free plan" at https://instabox.sh/docs/machines/auto-pause#longer-cooldowns-on-the-free-plan. Once cooldown ends, 0 still refuses wake with 409 max_run_disabled until changed.
-1 <= x <= 2147483647New name, unique among the org's live sandboxes; 1-63 of a-z, 0-9, '-', starting with a letter or digit. Absent: unchanged.
Admins only: new root filesystem size in GiB (the template sizes it). From anyone else it is 400 spec_not_allowed; grow the disk with persistentDiskGiB.
0 <= x <= 1024New vCPUs of a stopped paid sandbox: with memMiB, one of the workspace's allowedSpecs (alone: the one size with that many vCPUs); 0 or absent: unchanged. Applied at its next start (see the operation). Running is 409 operation_conflict (stop it first), and so is paused (resume it, then stop it); another size, or the free sandbox, is 400 spec_not_allowed.
0 <= x <= 32New memory (MiB) of a stopped paid sandbox, as vcpus; 0 or absent: unchanged.
0 <= x <= 131072New disk (/data) size in GiB, 1-1024, up to the plan's maxDiskGiB; 0 or absent: unchanged. Grow: a running box grows online (no restart, processes keep running); if it can't (rare: the box is unreachable or its host is older), 409 grow_needs_stop (stop it and send the size again); a stopped box grows at its next start. Shrink: only while stopped (else 409 operation_conflict), and only when the used data plus 10% (at least 1 GiB) fits; else 409 disk_too_small, with the smallest size that fits in the message, and the box unchanged. Past 1024 is 400 bad_request, and so is growing on a template without the root-grow capability (a shrink needs none); a free box's disk is fixed (400 spec_not_allowed, running or stopped). The Python SDK's machines.resize(m, disk_gib) sends this field.
0 <= x <= 1024Replaces the metadata (same limits as Metadata); {} clears it; null or absent: unchanged.
Show child attributes
Show child attributes
The plan's rule (AutoSuspendAfterSeconds): a paid sandbox takes 300-1800 in whole minutes, as sent, or 0 (off) where the plan allows always on; below 300, above 1800 or not a multiple of 60 is 400 bad_request; the free sandbox takes only 1800 (else 403 spec_not_allowed), and 0 without always on is 403 spec_not_allowed too. A refused value leaves the setting unchanged; the reply shows the effective value. API keys follow the owner's policy. Separately, with manual lifecycle (GET /v1/me) or an admin sign-in session: 120-86400, or 0 (off). Absent: unchanged.
False disables legacy Vault delivery; true cannot re-enable the legacy flag; absent is unchanged. Org Secret selections are independent.
restart: a running or paused sandbox whose change needs a stop is stopped, resized and started again by one resize operation (202); see the operation. Absent: such a change is 409. Anything else is 400 bad_request.
restart Response
The sandbox, updated.
A sandbox.
creating, starting, running, stopping, stopped, suspending, suspended, resuming, deleting, deleted, error creating, starting, running, stopping, stopped, suspending, suspended, resuming, deleting, deleted, error Increases with each accepted change.
The active operation, if any.
Show child attributes
Show child attributes
A sandbox's size.
Show child attributes
Show child attributes
The sandbox's storage (/data, where HOME lives).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The running sandbox is paused once it has been idle this many seconds (no agent working, no terminal input or output, little CPU); null: off. Pause, resume, stop and start keep it.
Maximum continuous runtime in minutes. -1 is unlimited; 0 sleeps immediately. Independent of idle auto-pause; whichever condition is reached first pauses the sandbox. Free machines default to 480 and only an admin session can change them. The service manages free runtime and may pause a run earlier. The response reports the current limit from runStartedAt; it can change during the run. Paid machines default to -1 and their users can change this setting. Max-run suspension starts a cooldown, returning 409 machine_cooldown with Retry-After on every wake path. By default it is 5 to 20 minutes (5 plus a random 0 to 15) on a paid plan and for the first such pause in a row on the free plan. Back-to-back pauses on the free plan rest longer (60 to 75, then 120 to 135 minutes): "Longer cooldowns on the free plan" at https://instabox.sh/docs/machines/auto-pause#longer-cooldowns-on-the-free-plan. Once cooldown ends, 0 still refuses wake with 409 max_run_disabled until changed.
-1 <= x <= 2147483647Start of the current continuous run, conservatively initialized on a first error observation too; resets only after confirmed sleep.
All wake paths are refused until this deadline, including admin actions: after a max-run suspension, or the 24-hour lock of an automatic abuse check's pause (cooldownReason).
String labels. At most 32 keys of 1-64 characters [A-Za-z0-9_.-], values of at most 512 characters, 8 KiB as JSON.
Show child attributes
Show child attributes
Whether legacy Vault delivery is enabled. Independent of org Secret selections and delivery status at the sandbox's /secrets endpoint.
The Linux user in the sandbox that SSH sessions, exec and the terminal log in as, fixed at create: the guestUser the create named, else user (a create from a snapshot: the snapshot's user). dev on sandboxes from templates without the guest-user capability, and on every sandbox created before the field.
"alice"
The org the sandbox counts against (docs/orgs.md).
Show child attributes
Show child attributes
Deprecated: snapshot, under its old name (same value).
Show child attributes
Show child attributes
Show child attributes
Show child attributes
When the sandbox is stopped if it is running (set at creation with archiveSeconds): its files are kept and a start brings it back. Resuming does not clear it; a sandbox that is not running when it passes only has it cleared. Absent: none.
When the sandbox is deleted, whatever its state (set at creation with deleteAfterSeconds). The delete is an ordinary delete operation (trigger: delete_at), queued at deleteAt (within about a second) once no other operation is in progress. Absent: never.
When the running sandbox last became ready (runtime.ready turned true: SSH, exec and files work). For a new sandbox, readyAt minus createdAt is its create time; after a start or resume it is that start's. Absent while the sandbox is not ready, and on a sandbox that was already ready before the field existed (until its next start or resume).
While cooldownUntil has not passed, the automatic abuse check whose pause locks the sandbox, the same as a wake's 409 machine_cooldown Error.reason: abuse_egress_blocklist (it tried to connect to a blocked destination on the egress blocklist, not a DNS lookup), abuse_network_flows (scanning or attack traffic), abuse_cpu (mining). Absent for a max-run cooldown, and once the lock ends.
abuse_egress_blocklist, abuse_network_flows, abuse_cpu With cooldownReason: what the owner is told about the pause behind the lock. Absent when cooldownReason is.
Show child attributes
Show child attributes
When the sandbox was queued to pause automatically; a successful automatic resume or its next explicit operation clears it. Absent: none.
The names of the sandbox's create-time env, sorted. Absent when it has none. The values are never shown: read them in the sandbox.
A free-tier org's sandbox (docs/pricing.md): never billed, pauses after 30 idle minutes (another autoSuspendAfterSeconds is refused with 403). On a paid plan every sandbox is billed.
Set on a stopped or paused free sandbox that cannot be started because its org's early free-sandbox allowance ended and as many free sandboxes as the standard limit allows are running: a start is refused (402 early_allowance_ended) until one is paused or deleted. Absent otherwise.
Processes the sandbox's kernel OOM killer killed since the sandbox was created (out of memory, or a memory cgroup's limit). Read from the sandbox about once a minute while it runs, and after an exec that exits non-zero; 0 on sandboxes whose host or guest agent predates the reading (absent from older servers).
The newest OOM kill (absent until one is seen, or when the kernel log no longer held it).
Show child attributes
Show child attributes
Was this page helpful?