Run one command in a sandbox made for it

Creates a sandbox, runs the command in it, answers with the result and deletes the sandbox. The sandbox lives exactly as long as the request: it goes when the command ends and when the caller hangs up. The command gets 300 seconds unless timeout_seconds says otherwise. The call waits for the command however long it runs: there is no 202 here. A sandbox that was given a name has left the node's table, and its name is free, before the answer says that the command has ended (the JSON answer, or the exit, error or end event of a stream): the next call can give the same name at once.

As a stream (text/event-stream): its events are start, stdout, stderr, gap, exit and error: Event streams and terminals.

Takes write and exec.

POST

https://api.glac.ai/v1/run

Autorisation

apiKeyHTTPrequired

Paramètres d’en-tête

X-Request-Idoptionalstring
The caller's own id for the request: 1 to 64 letters, digits, ., _ and -. The node then knows the request by it: in the answer's X-Request-Id, in error bodies and in its log. Anything else is ignored, and the node makes an id.

pattern: ^[A-Za-z0-9._\-]{1,64}$
Idempotency-Keyoptionalstring
Makes the request safe to send again. See "Idempotency-Key" in the introduction.

maxLength: 255 · minLength: 1

Corps de la requêteJSONobligatoire

commandrequired
A string is one line for sh -c; a list is run as it is, without a shell, its first word found as a shell finds it: along the PATH of the command's own environment (the image's, with what env says). At most 1000 arguments, no NUL bytes.
L’une des variantes suivantes :
string
array<string>
}
startoptionalboolean
true: start the image's own start command (ENTRYPOINT and CMD) when the machine boots; false: start nothing, whatever the image's labels ask for. Given (as any of start, start_command and ready), it is all that counts: the image's labels sbx.start and sbx.ready are not read. The sandbox is made from a template built with these settings and env (two settings of one image are two templates; the first sandbox of a setting is returned starting while it is built), which only its owner's sandboxes are made from. Not for a sandbox made from a snapshot or a template (400 invalid_start).
start_commandoptional
The start command, run as the image's user, its output kept by the sandbox's agent as that of the command exe-start (the last 16 MiB of it, read like any command's with GET …/exec/exe-start and …/exec/exe-start/output; for an app's instance it is also what the app's log has of the instance): a string is run by /bin/sh -c and may hold several lines; a list is run as it is, without a shell (for an image that has none). At most 1000 arguments and 64 KiB, no NUL bytes, the first argument not empty. With start: false, 400 invalid_start.
L’une des variantes suivantes :
string
array<string>
}
readyoptional
When the machine of the sandbox's template counts as up: the node saves the template, which every sandbox of these settings is cloned from, only once this check passes, so that the service is running in each of them from the start. One of three. tcp and http are tried by the node from the host, at the address the preview URLs reach the sandbox by: nothing runs in the sandbox for them, so an image without a shell can be checked, and the service has to listen on all addresses, not on 127.0.0.1 alone. command runs in the sandbox as the image's user, by sh, like the label sbx.ready. Tried every 0.2 s for at most 120 s; a start command that ends with a failure meanwhile ends the wait at once. Either way the sandbox fails with failure_code boot_failed, and failure says what the check last got and what the start command printed last. Needs start: true or start_command (400 invalid_start). Not given: the template is saved without waiting.
L’une des variantes suivantes :
object
object
object
}
egressoptionalobject | null
What the sandbox may reach, and which of its requests get a secret added, as in SandboxCreate.
- defaultoptionalallowoudenyounull
- allowoptionalarray | null
- denyoptionalarray | null
- httpoptionalarray | null
- injectoptionalarray | null
- deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, whatever else the rules say: at most 64, each from 1 to 65535. Null or empty: none.
}
guest_mitigationsoptionalboolean
Whether the guest kernel keeps its mitigations against speculative execution. They guard the guest's kernel against processes in the same sandbox: turn them on when a sandbox runs code of several users who do not trust each other. Sandboxes are kept apart from each other by the host either way. Default: the node's setting (off). The setting is fixed when the kernel boots: the first sandbox with a setting other than its image template's starts like a new image (returned starting), and a sandbox made from a snapshot keeps the snapshot's (asking for the other is 400).
tmpoptionaldiskoumemory
Where the sandbox's /tmp is. disk: on its disk, as the rest. memory: a tmpfs of at most half of its memory, mounted before its first command (in a sandbox made from a template or an image, over what the template's guest had put there; by the guest's init where it starts from its disk): what is written there is the guest's memory, billed as memory, kept when it sleeps, and gone when it starts again from its disk. A sandbox made from a snapshot whose sandbox had it in memory has it so whatever this says.

default: "disk"
runtimeoptional
Runtime settings of its machine and its commands, as a Compose file's ulimits, sysctls, tmpfs, dns and shm_size ask for them (Runtime). For a sandbox made from an image: they make a template of the caller's own, built with them (with nothing said of the start, the image is started as its labels ask). Refused for one made from a snapshot or a template (400 invalid_start), which goes on with what its machine has.
L’une des variantes suivantes :
NodeRuntime
ulimitsoptionalobject | null
By Docker's names (core, cpu, data, fsize, locks, memlock, msgqueue, nice, nofile, nproc, rss, rtprio, rttime, sigpending, stack): a number for both limits, or {soft, hard}, the soft no higher than the hard; -1 is none. nofile from 1 to 1048576 (the guest's fs.nr_open), never -1. Shown as {soft, hard}.

sysctlsoptionalobject | null
Those Docker lets a container set, by name: net.*, kernel.shm*, kernel.msg*, kernel.sem, fs.mqueue.*; a value of 1 to 1024 bytes on one line. Shown as strings.

tmpfsoptionalarray | null
Mounted with set-user bits and devices off.

dnsoptionalobject | null
/etc/resolv.conf in the place of the image's. Where the node answers a sandbox's questions itself (on its project's network; egress rules that can refuse a name), it answers in the place of the servers named: they are asked directly only by a sandbox it does not answer for.

serversoptionalarray | null
searchoptionalarray | null
optionsoptionalarray | null
shm_size_bytesoptionalinteger | null
maximum: 1099511627776 · minimum: 1048576
null
}
initoptional
What the sandbox's PID 1 is. Not given, or null: the platform's init, which starts the image's start command where there is one (start, start_command, the image's labels). systemd: a whole system. The image's own systemd is PID 1 and the node's agent is one of its services: the user installs packages, starts services with systemctl, uses cron and the journal and logs in by SSH, as on a machine. Nothing a create names is started (start, start_command and ready are refused with 400 invalid_start), and the template is saved once systemd says the machine has booted. Without image: the node's image of a whole system (--systemd-image; Ubuntu 24.04 with systemd and OpenSSH, sandboxd/images/ubuntu), refused with 400 invalid_start on a node that has none. An image without systemd (/usr/lib/systemd/systemd) fails its build, with failure_code invalid_image. Its template is anybody's who asks for the same image so, unless something of the caller's is in it (runtime, image_pull_secret). Refused for one made from a snapshot or a template (400 invalid_start), which goes on as its machine was. Everything else a sandbox does works as for any sandbox: commands, files, terminals, the SSH gateway, sleep and wake, snapshots and forks, moves, egress rules (sandboxd/README.md, 「整个系统：systemd 当 PID 1」).
L’une des variantes suivantes :
string
null
}
project_networkoptionalboolean
true: the sandbox is on its project's private network from before it runs anything, at the first of the addresses the node was left to spare for the project (setProjectNetwork): the answer says which (project_address). The project is the call's owner, so this is for a call the control plane makes for a project; on a node that stands alone a sandbox is nobody's, and is put on a network by being named in it. A sandbox is on no project's network unless it asks: default false. A copy made by a fork is on none, whatever its original is on.
imageoptionalstring
An OCI image reference (python:3.12, ghcr.io/org/app@sha256:…), in a registry on the internet: one that gives the image to anybody, or one that wants a login, with image_pull_secret. The first sandbox of an image is returned starting while the node pulls the image and builds a template; later ones start from the template. Default: the node's base image.

maxLength: 512
image_pull_secretoptionalstring
The name of a secret (PUT /v1/secrets/{name}) that holds the credentials of the image's registry, for an image that is not public: username:password in printable ASCII, the user name ending at the first colon. A registry that takes a token alone documents the user name that goes with it (AWS for ECR, oauth2accesstoken for Google's, any name for GHCR). The node hands the credentials to the tool that pulls the image and to nothing else: nothing of them is in the sandbox, in its template or in the node's log, and what a registry says when it refuses them comes back without them (failure_code registry_auth_failed). The sandbox is made from a template of its owner's alone, which a create that names credentials finds and no other: the same image named without them is asked of its registry without a login, whether or not the node has the template. The secret has to exist (404 secret_not_found), to be one that may go to the image's registry (its allowed_hosts cover the registry's host as the reference writes it, without its port, docker.io where it names none; 403 secret_host_not_allowed otherwise) and to hold such a pair (400 invalid_field), and it goes with image (400 invalid_field for a sandbox made from none).

maxLength: 128
snapshotoptionalstring
A snapshot's id or name: the sandbox goes on from the instant the snapshot was taken, processes included.
templateoptionalstring
A template's key on the node (base, img-…), as GET /internal/node lists them. Not in the reference README; the benchmark scripts use it.
limitsoptionalobject
The shape a create asks for. Each part that is not given (or is null) is the node's base template's, which is what a sandbox that asks for none gets. Up to the most this node gives a sandbox, max_vcpus and max_memory_bytes of GET /internal/node (by default the host's CPUs, up to 32, and its memory; never less than the base template's shape); more is 400 invalid_field. Each shape of an image is a template of its own: the first sandbox of a shape the node has not built that image in is returned starting while the node builds it, from the same image, and later ones are cloned from it. Without image, another shape than the base template's is built from the node's base image. A sandbox made from a snapshot or a template has that one's shape: asking for it is fine, for another 400 invalid_field (param limits). The disk's size is the node's: disk_bytes is 400 invalid_field.
- vcpusoptionalinteger | null
  Virtual CPUs.
  
  maximum: 32 · minimum: 1
- memory_bytesoptionalinteger | null
  Memory, in bytes: an even number of MiB (a whole number of 2 MiB pages), 128 MiB or more. Any other size is 400 invalid_field (param limits.memory_bytes), as is the same size in a template made ahead (POST /internal/templates) and a shape of the ready list (ready_images.unread_lines): a node that keeps its templates' memory in huge pages loads a machine's memory in 2 MiB pages, and Firecracker refuses to load one of another size, so a template of 285 MiB would be built and every sandbox made from it fail. Not rounded: a sandbox has the size it is asked for, or is refused.
  
  format: int64 · minimum: 134217728
}
nameoptionalstring
A name given by the caller to a sandbox, a snapshot, a volume or an SSH key: 1 to 63 lower-case letters, digits and hyphens, not starting or ending with a hyphen, and not starting with an id prefix (sbx-, exe-, snap-, vol-, evt-, req-; an SSH key's not with sshkey- either). A DNS label that cannot be taken for an id. Unique among sandboxes, among snapshots, among volumes and among SSH keys.

pattern: ^[a-z0-9]([a-z0-9\-]{0,61}[a-z0-9])?$
envoptionalmap destring
Added to the sandbox's env for this command; the same name wins here.
metadataoptionalmap destring
Free key-value pairs for the caller's own use; lists of sandboxes filter by them. At most 64 keys of 1 to 64 characters, values of up to 1024. Not a place for secrets: metadata are stored in clear, and every set of them a sandbox has had while it used something is kept with its usage for thirteen months, also after the sandbox is deleted (GET /v1/usage groups and filters by them).
volumesoptionaltableau deobject
Volumes to mount before the call returns. At most two that are not shared.
- pathstringrequired
  Where the volume is mounted in the sandbox: an absolute path other than /.
- volumestringrequired
  The volume's id or name.
- read_onlyoptionalboolean | null
  Mount it read-only. For a shared volume this is enforced on the node, not in the sandbox.
  
  default: false
- copyoptionalboolean | null
  true: a volume that is new (its file system holds nothing yet) is given what the sandbox's image has at path when it is first mounted, as Docker gives a new named volume: every file, directory and link, with its owner, mode, times, extended attributes and hard links (a database image's data directory, with the owner its server wants); and it is left empty then, without lost+found, as a new named volume is (a server that sets up its data directory refuses one that holds anything). A volume that holds something is mounted as it is. Only when a sandbox is made: a volume attached later (PATCH) takes no copy (400 unknown_field).
  
  default: false
- versionoptional
  A version of the Drive volume names, as a snapshot of it says it (slice D7): the sandbox is given a read-only view of that version, its own, fetched from the store as it is read, whatever has the Drive and wherever it is (the Drive may be deleted since). Mounted read-only.
  
  L’une des variantes suivantes :
  DriveVersion
  namestringrequired
  Its root's name in the store.
  
  pattern: ^disks/vol-[0-9a-hjkmnp-tv-z]{16}/e[0-9]+/r[0-9]{10}-[0-9a-f]+$
  bytesintegerrequired
  format: int64 · minimum: 0
  epochintegerrequired
  format: int64 · minimum: 1
  numberintegerrequired
  format: int64 · minimum: 1
  tokenstringrequired
  pattern: ^[0-9a-f]+$
  refsstringrequired
  Its list of references, in the store: what the control plane's collector keeps for it.
  
  storestringrequired
  The identity of the store its root, pages and frames are in.
  
  keystringrequired
  The number of the key it is sealed with (empty where a version from before keys were numbered).
  
  null
}
public_portsoptionaltableau deinteger
Ports anybody may open at their short preview URL.

maximum: 65535 · minimum: 1
public_ports_exceptoptionalarray | null
Every port but these is public as well: its short preview URL opens it for anybody, as a port in public_ports (how E2B makes a sandbox's ports; the control plane's E2B compatibility gives [49983], envd's port, which a sandbox token opens). []: every port. Null (the default): only public_ports. Ports are taken once each, in order.
inboundoptionalarray | null
Ports open to the internet at the sandbox's own IPv6 address from the start, each with its sources (…/tcp/{port} opens one later). A node without a pool of addresses refuses a list that is not empty: 409 no_ipv6.
sleep_after_secondsoptionalnumber | null
Sleep after this long idle. Null: never by itself. The default is the node's (--sleep-after-seconds, 30 unless set).

maximum: 1000000000 · minimum: 1 · default: 30
expires_atoptionalstring | null
Delete the sandbox at this time, which must be in the future (or what on_expiry says). Null or absent: never.

format: date-time
on_expiryoptionaldeleteousleepouholdounull
What expires_at does when it comes: delete the sandbox (null or absent: this); sleep, put it to sleep whatever goes on in it, and keep it (its expires_at is null from then on, and a request wakes it as ever); hold, the same, held asleep (held_asleep is set then: a request does not wake it). How E2B pauses a sandbox when its time is up (the control plane's E2B compatibility). Another word is 400 invalid_field.

default: "delete"
held_asleepoptionalboolean | null
True: while it sleeps, a request to one of its ports does not wake it: the preview listener answers 502 sandbox_paused in its place, as E2B's proxy answers for a paused sandbox (x-preview-ingress), and only a call of the API (or its own timer) wakes it. It is not put to sleep by this: POST /v1/sandboxes/{id}/sleep does that. False or null: as any sandbox. (E2B's pause without its autoResume, which the control plane's E2B compatibility sets, and takes away at its connect.)

default: false
sleep_notice_msoptionalinteger | null
As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

maximum: 60000 · minimum: 0
sleep_hold_max_msoptionalinteger | null
As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

maximum: 900000 · minimum: 0
suspend_after_msoptionalinteger | null
As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

maximum: 86400000 · minimum: 1000
wake_daily_atoptionalstring | null
As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
checkpointoptional
As in SandboxCreate: accepted, and its checkpoints taken while the command runs.
L’une des variantes suivantes :
object
null
}
delete_after_idle_msoptionalinteger | null
As in SandboxCreate: accepted, and of no effect, since the sandbox never sleeps.

format: int64 · minimum: 1000
hostnameoptionalstring | null
As in SandboxCreate.

maxLength: 63 · pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$
stopoptionalobject | null
How the sandbox's start command is stopped before its machine is ended for good: before a restart (POST /v1/sandboxes/{id}/restart) and a delete. The signal goes to the start command, which is then given grace_ms to end; what has not ended then goes with the machine. A machine that sleeps or is paused is not stopped: it goes on from where it was. Not given: the start command goes with its machine, as it always has. Unknown keys: 400 unknown_field; a signal that is none of these, or a grace beyond ten minutes: 400 invalid_field.
- signaloptionalSIGTERMouSIGINTouSIGQUITouSIGHUPouSIGUSR1ouSIGUSR2+15 autres
  By its name, with SIG or without. Null: the image's own (its STOPSIGNAL), else SIGTERM.
- grace_msoptionalinteger | null
  Null or not given: 10000.
  
  maximum: 600000 · minimum: 0
}
secret_envoptionalmap destring
As in SandboxCreate: more variables, whose values are secrets, the sandbox's and so the command's; none of them in env too (400 invalid_field, param secret_env.<name>). No answer shows a value.
cwdoptionalstring
An absolute path to run in. Default: the image's working directory. A directory that does not exist is not an error of the call: the command ends with exit code 126.
useroptionalstring
A user name, a uid, or uid:gid. Default: the image's user.

maxLength: 64 · minLength: 1
timeout_secondsoptionalnumber
As in RunRequest, with a default: nothing else would stop the sandbox.

maximum: 1000000000 · default: 300
stdinoptionalstring
Fed to the command's input, which is then closed (unless stdin_open). Base64 when encoding says so. The whole request is 64 MiB at the most (413 body_too_large beyond): a longer input goes in …/exec/{exec_id}/stdin calls, or in a file first.
encodingoptionalutf8oubase64
base64: stdin is base64, and stdout and stderr come back as base64 (in a stream: events carry base64 instead of text). For output that is not text.

default: "utf8"
streamoptionalboolean
Answer with an event stream. Default: true if the request's Accept contains text/event-stream.
wait_for_readeroptionalboolean
Have the command wait for whoever reads this call's answer, instead of running ahead of it. As in RunRequest.

default: false
regionoptionalnaoueuouapounull
The region to make it in, read by the API and not passed on. Null or left out: the region the API itself runs in. Where no machine of that region can take it, the next region does; what has to go to one machine (made from a snapshot or with volumes, or sent again with the same Idempotency-Key) goes there, whatever the region. A volume made from a backup is made in the backup's region: another is 400 invalid_field. Not a region: 400 unknown_region. The answer's region says where it was made.

Returns

200

The command has ended: its result as JSON, or the event stream that led there. sandbox_id names the sandbox, which no longer exists.

JSON

idstringrequired
exe- and 16 characters. With an Idempotency-Key it is derived from the sandbox's id, the call (run or exec) and the key.

pattern: ^exe-[0-9a-hjkmnp-tv-z]{16}$
objectstringrequired
sandbox_idstringrequired
pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
commandstringrequired
The command as text: the line, or the arguments joined by spaces; shell for a terminal started without a command. At most 1024 characters. A command that came with a snapshot or a fork is listed as it was where it started: the sandbox keeps this itself.
ttybooleanrequired
Whether it runs on a terminal.
statusstringrequired
exited: it ended by itself, with any exit code. timed_out: timeout_seconds was up. killed: a signal ended it.
exit_codeinteger | nullrequired
Null while running. 128 plus the signal's number when a signal ended it. A non-zero code is a result, not an error.
signalstring | nullrequired
The signal that ended it, as SIGTERM, SIGKILL, … or SIG<number> for one the daemon has no name for; null otherwise.

pattern: ^SIG[A-Z0-9]+$
started_atstringrequired
From the sandbox's clock: the same in the full object and in a list.

format: date-time
pidintegerrequired
Its process id in the sandbox.
duration_secondsnumber | nullrequired
Wall time from start to end. Null while running.

minimum: 0
usagerequired
Null while running.
L’une des variantes suivantes :
ExecUsage
cpu_secondsnumberrequired
User and system CPU time of the command and the children it waited for.

minimum: 0
max_memory_bytesintegerrequired
The largest resident set of any of them.

format: int64 · minimum: 0
null
}
outputobjectrequired
How much the command has written and which part of it can still be read.
- stdout_bytesintegerrequired
  Bytes written to stdout so far.
  
  format: int64 · minimum: 0
- stderr_bytesintegerrequired
  format: int64 · minimum: 0
- startintegerrequired
  The position of the oldest byte still kept. Positions count the bytes of both streams together, in the order they were written; the sandbox keeps the last 16 MiB.
  
  format: int64 · minimum: 0
- endintegerrequired
  The position after the newest byte.
  
  format: int64 · minimum: 0
}
stdoutstringrequired
The last 1 MiB of stdout. Text, with bytes that are not UTF-8 replaced; base64 when encoding is base64.
stderrstringrequired
The last 1 MiB of stderr.
truncatedbooleanrequired
True when either stream was longer than 1 MiB, or part of the output was no longer kept.
encodingstringrequired
How stdout and stderr are written: as the request asked.

EVENT-STREAM

string

400

The request is not one this call takes. invalid_json: the body is not a JSON object; unknown_field: the body has a field this call does not take; unknown_parameter: the query has a parameter this call does not take; invalid_field: a field or query parameter has the wrong type or is out of range; invalid_name: name is not a valid name; invalid_env: env has a name or a value an environment cannot hold; invalid_metadata: metadata is over its limits; expires_in_the_past: expires_at is not in the future; invalid_egress: egress is not a set of rules: param names the part that is wrong; invalid_start: start, start_command and ready do not go together as given (ready without a start command, start: false with start_command), or one of them is given with init: "systemd", whose systemd starts what its units say, or init: "systemd" names no image on a node that has no image of a whole system (--systemd-image), or the sandbox is made from a snapshot or a template: param names the field; ambiguous_source: more than one of image, snapshot and template; invalid_image: image is not a reference to an image in a registry on the internet; invalid_path: a volume's path is not absolute or is /; missing_command: no command; no_such_user: user is not a user of the sandbox; invalid_idempotency_key: Idempotency-Key is empty or over 255 characters.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

401

missing_api_key, invalid_api_key, expired_api_key, invalid_token.

JSON

errorobjectrequired
- typestringrequired
- codestringrequired
- messagestringrequired
- paramstring | nullrequired
- retryablebooleanrequired
- request_idstringrequired
- docs_urlstring | nullrequired
}
move_idoptionalstring
With already_moving: the move of the sandbox that is under way.
upgrade_idoptionalstring
With upgrade_in_progress (the key's upgrade that is not over), upgrade_started (the upgrade that has begun) and rollback_gone (the upgrade whose revert is refused): that upgrade.

pattern: ^upg-[0-9a-hjkmnp-tv-z]{16}$
moveoptionalobject
With move_over, move_going_back and move_taken_over (POST /internal/moves/{id}/cancel): the move, as it stands.
- objectstringrequired
- idstringrequired
  pattern: ^mov-[0-9a-hjkmnp-tv-z]{16}$
- sandbox_idstringrequired
- project_idstringrequired
- fromobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- toobjectrequired
  idstringrequired
  namestring | nullrequired
  Its name; null for a node that is off the books since.
- epochintegerrequired
  The epoch the table held the sandbox at when the move began: the old node releases it at it, the new one takes it over one on, the old one takes it back two on, and from the object store three on.
  
  minimum: 1
- stepstringrequired
  Where it stands: releasing (the old node is asked to release it; the table has it there), taking_over (the new node is asked to take it over; the table has it there), reclaiming (the new node refused it, and the old one is asked to take it back), restoring (the old one kept nothing of it, and takes it over from the object store), done (on the new node), failed (where it was, or back there, or where a failure no time clears or an operator's cancel found it: error says why).
- whystringrequired
  What made it: the operator's move, an evacuation, a recovery.
- wakebooleanrequired
  Whether the new node wakes it: as the call said, or as it was (it ran) when the move began.
- from_storebooleanrequired
  The new node takes it from the object store alone.
- releaseobject | nullrequired
  What the old node's release answered (sandboxd/openapi/openapi.json, releaseSandbox), without the release's key; null before it answered.
- takeoverobject | nullrequired
  What the takeover that ended it answered (takeoverSandbox of the node's document): where its disk and memory came from (source), how long each took (ms), memory; null before.
- errorrequired
  Why it failed, of one that failed (the new node's refusal, where it was taken back to the old node); null, of one that is done; of one under way, what the step it is at was last told where it is asked again.
  
  L’une des variantes suivantes :
  object
  null
- attemptsintegerrequired
  How many times the step it is at was asked without an answer that settles it.
  
  minimum: 0
- next_attempt_atstring | nullrequired
  When that step is asked again; null where it is not waiting.
  
  format: date-time
- batchstring | nullrequired
  The evacuation (evc-…) or recovery (rcv-…) it is of.
- created_atstringrequired
  format: date-time
- updated_atstringrequired
  format: date-time
- ended_atstring | nullrequired
  format: date-time
}
lease_untiloptionalstring
With lease_held: until when the node may still hold the lease it was granted last, and the time after it for the node to have seen it run out (recoverNode is refused until then).

format: date-time
activeoptionalobject | null
With standby: the active copy, as the standby last read the lease; null while no copy holds it.
- namestringrequired
- urlstringrequired
- termintegerrequired
  minimum: 1
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none (the node's SecretHosts).
problemsoptionaltableau deobject
With invalid_definition: every problem of the definition, each where it is and what it is.
- atstringrequired
  Where in the definition, a dotted path (services.web.port); empty for the whole of it.
- messagestringrequired
}
reportoptionalobject
With compose_refused: the import's report, which says what is refused, why, and what to change.
- objectcompose_importrequired
- namestring | nullrequired
  The model's name: each service's label compose.project. Null: it has none.
- dry_runbooleanrequired
- strictbooleanrequired
- profilestableau destringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemstableau deobjectrequired
  The model's top-level elements: name, each volume, network, config and secret, extensions.
  
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneouadaptedouignoredourefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
- servicestableau deobjectrequired
  The services the import takes, in the model's order.
  
  namestringrequired
  The service's name, which is its app's.
  
  app_idstring | nullrequired
  Its app. Null: a dry run of a service the project does not have.
  
  pattern: ^app-
  statuscreatedouchangedouunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceoujobrequired
  job: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it.
  
  statefulbooleanrequired
  It mounts a volume of its own: one instance, which has the volume.
  
  versionbooleanrequired
  Whether the import's deploy makes a version of it: what its version would be made of, its references resolved, is not what its current version is.
  
  itemstableau deobjectrequired
  atstringrequired
  Where in the model: of a service, its attribute (ports[0], depends_on.db, environment.KEY), empty for the service as a whole; of the top level, the element (volumes.db-data).
  
  treatmentdoneouadaptedouignoredourefusedrequired
  done: it means the same on the platform; adapted: the platform does the same another way; ignored: it matters to a local run alone (refused with strict); refused: the platform cannot do it, and doing without it would let the program go wrong quietly.
  
  whystringrequired
  changestring | nullrequired
  Of one that is refused: what to change. Null otherwise.
  
  appobjectrequired
  The fields of the service's app as the import writes them: what its versions are made of, and what holds at once.
  
  imagestring | nullrequired
  What the app's next version is made of, with the seven fields after it: its newest version's, with what was changed since. null: the app has no image, and no version.
  
  image_pull_secretstring | nullrequired
  The name of the secret that holds the credentials of the image's registry. No answer has its value. null: none.
  
  start_commandrequired
  L’une des variantes suivantes :
  StartCommand
  null
  start_argsrequired
  What follows the image's ENTRYPOINT in the place of its CMD. null: the image's CMD, or the whole of start_command.
  
  L’une des variantes suivantes :
  array<string>
  null
  portinteger | nullrequired
  readyobjectrequired
  How to tell that an instance is up, which a version's template is saved after: exactly one of the three. The first two are asked from outside the instance, so the service has to listen on every address (0.0.0.0).
  
  httpoptionalstring
  A path, beginning with /: a GET of it on the app's port is answered with a status from 200 to 399.
  
  tcpoptionaltrue
  The app's port takes a connection.
  
  commandoptional
  A command that succeeds in the instance. It is run by the instance's shell: a list of arguments is written as one line for it.
  
  L’une des variantes suivantes :
  string
  array<string>
  envmap destringrequired
  secretsmap destringrequired
  Names of secrets. No answer has a value.
  
  sizeobjectrequired
  What one instance may use at most. It is billed by what it uses.
  
  vcpusintegerrequired
  minimum: 1
  memory_bytesintegerrequired
  An even number of MiB (a whole number of the 2 MiB pages a node loads a machine's memory in), in bytes. Any other size is 400 invalid_field (param size.memory_bytes): no node would make an instance of it, as none makes a sandbox of it (the node's SandboxLimitsCreate.memory_bytes).
  
  minimum: 134217728
  volumestableau deobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filestableau deobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  L’une des variantes suivantes :
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionstableau destringrequired
  In the order na, eu, ap.
  
  scaleobjectrequired
  min_instancesintegerrequired
  How many instances of the app are kept awake in a region, whether a request comes or not: the floor. The nodes of the region that serve the app share it as they share max_instances (two nodes and a floor of 2: one on each; a floor of 1: one, on the node that is tried first; a floor of 5: three and two), and a node that is away is made up for by the others. A node makes its part when it is told, not at the first request, and neither stops nor deletes those instances for being idle; they are metered as instances that are awake. 0, which is what it is when nothing is said: none. Lowered, the instances beyond it are idle from that moment, and are stopped and deleted as idle instances are. At most max_instances, where that is given, and at most what the account's plan lets an app ask for in a region (caps.app_instances.limit: 5, 50 and 500): more is refused, 403 plan_cap_reached.
  
  minimum: 0
  max_instancesinteger | nullrequired
  How many instances the app has at the most in a region: the nodes of the region that serve the app share it. At most what the account's plan lets an app ask for (caps.app_instances.limit: 5 on Free, 500 on Paid): more is refused, 403 plan_cap_reached, and what an app asked for on a plan that let it is kept, and held to the plan's number. null: the plan's number for an app that names none (caps.app_instances.default: 2 on Free, 50 on Paid), or min_instances where that is more. What the nodes are told is no more than the account has room for awake beside everything else of it that is awake, nor less than the app has awake.
  
  minimum: 1
  concurrencyinteger | nullrequired
  A cap on what one instance has in hand at a time: the requests the edges sent it, and the connections it has open on its project's network (through its service's address, which the node shares out among the instances connection by connection, or to its own). An instance with that many is full, and another is made for more. null, which is what it is when nothing is said: no cap. A node then adds an instance when the ones it has are near their size in CPU or memory, and an app does not have to guess a number; a service that takes one request at a time gives one.
  
  maximum: 1000 · minimum: 1
  sleep_after_msinteger | nullrequired
  The most an instance waits without a request before it stops, in milliseconds. Below it, its node picks the wait by the app's own traffic: the wait that would have cost least over the app's last gaps between a request's end and the next one, a second up and idle against a stop and the resume after it in CPU time, so that an app whose requests come closer together than a stop pays for stays up through them, and one whose requests are far apart stops as soon as its last answer has ended (0: stops at once, always). null, which is what it is when nothing is said: the platform's most, three seconds. An app that said 100, the default before 2026-10-28, says null from then on. One that stays stopped is deleted by its node after delete_after_ms, and the next request that needs an instance gets a new one; the instances min_instances keeps awake are neither stopped nor deleted.
  
  maximum: 600000 · minimum: 0
  sleep_notice_msinteger | nullrequired
  How long before an instance stops for being idle the programs connected to its guest's /run/sbx/awake are sent the line sleep N, in milliseconds: they flush what they hold, close their connections, or raise a hold, which puts the stop off. The stop comes that long after, whether they answer or not; where nobody is connected, it is not put off. A keyed instance is told as well. 0 or null: not told (the default).
  
  maximum: 60000 · minimum: 0
  sleep_hold_max_msintegerrequired
  How long the holds a program in an instance raises keep it up after its time idle has run out, in milliseconds: a program connects to /run/sbx/awake and sends + before it answers a request whose work goes on after the answer, and - (or closes the connection, or dies) when that work is done; the instance stops sleep_after_ms after the last hold is lowered. Past this time it stops whatever holds it, the programs connected told sleep N cap first where sleep_notice_ms asks for a notice. Held, it runs and is metered as running. 0: holds are not heeded. Null: 30000 (the default).
  
  maximum: 900000 · minimum: 0
  delete_after_msinteger | nullrequired
  After how long idle an instance is deleted, counted from where its stop is counted from: the next request that needs one gets a new instance, a clone of the version's template, without what the deleted one had gathered in its memory and on its disk (keep what is to last in a volume or a database). A second to an hour, the platform's time, which is the most: more is refused (400 invalid_field), and an instance that is to stay warm is one of min_instances. null, which is what it is when nothing is said: the hour of the nodes (--app-delete-after-seconds). A change holds for the instances the app has as for the ones made after: each node judges every instance by the app's time as it is, once a second at the least. Not for the app's keyed instances, which keys.delete_after_idle_ms is for.
  
  maximum: 3600000 · minimum: 1000
  suspend_after_msoptionalinteger | null
  How long a stopped instance stays paused before its memory is saved and it sleeps for real, in milliseconds: paused, the next request is answered in a millisecond or two and its memory is metered; asleep, it wakes in a few more and only what it keeps is. Its node holds it to the longest it holds any instance paused (ten minutes); the host's memory running short, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null (the default): its node's longest. A database's suspend_after_seconds is its app's.
  
  maximum: 86400000 · minimum: 1000
  wake_daily_atoptionalstring | null
  A time of day in UTC, HH:MM, at which the app's keyed instances and its stateful service's instance that rest are woken every day, for work of their own that waits for a wake (a database's maintenance, say); the instances the nodes make and delete by the app's requests are woken by requests alone. The wake is no activity: what runs then is, and once that is done the instance rests again. A stateful service's instance is woken besides for the next run of its PostgreSQL server's pg_cron jobs, whatever this says. Null (the default): none. A database's wake_daily_at is its app's.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
  keysrequired
  L’une des variantes suivantes :
  object
  null
  egressobject | nullrequired
  Egress rules as a sandbox has them (default, allow, deny, http, inject), null when there are none; kept as the calls gave them (a PATCH merges them key by key, as a node does). They hold at once and make no version: the nodes that serve the app put them on every instance of its group, the ones there are (one that runs for the connections it has too) and the ones made after; a keyed instance does not have them. The control plane checks only that they are an object of those keys of at most 256 KiB: what the rules say is a node's to check, when it applies them, and an instance whose rules its node cannot read is refused everything (the node's log says why).
  
  defaultoptionalallowoudenyounull
  allowoptionalarray | null
  denyoptionalarray | null
  httpoptionalarray | null
  injectoptionalarray | null
  deny_portsoptionalarray | null
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say. A Browsers session's always hold 25, 465, 587 and the ports mining pools listen on (3333, 4444, 5555, 7777, 14444, 45700): the control plane adds them to whatever a change of its rules gives.
  
  metadatamap destringrequired
  logsobjectrequired
  What the app's log has, each part as it was given or at its default (AppLogSettings).
  
  outputbooleanrequired
  keepbooleanrequired
  requestsobjectrequired
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  keep_errorsbooleanrequired
  publicbooleanrequired
  Whether it answers at its default domain (url).
  
  depends_ontableau deobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasestableau destringrequired
  endpoint_modestringrequired
  drivesoptionaltableau deobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionaltableau deobject
  The Drives each key's instance has of its own (AppCreate.key_drives): none, [], where it gives none.
  
  namestringrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  format: int64
  nocopyoptionalunknown
  There only where it was given as true.
  
  runtimeoptional
  Its runtime settings (AppCreate.runtime). null: none.
  
  L’une des variantes suivantes :
  Runtime
  ulimitsmap deRuntimeLimitGivenrequired
  sysctlsmap destringrequired
  tmpfstableau deobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serverstableau destringrequired
  searchtableau destringrequired
  optionstableau destringrequired
  shm_size_bytesinteger | nullrequired
  null
  tracesoptionalobject
  What the app's requests' traces have, each part as it was given or at its default (AppTraceSettings): no span where sample_rate is 0.
  
  sample_ratenumberrequired
  maximum: 1 · minimum: 0
  trust_incomingbooleanrequired
- volumestableau deobjectrequired
  The volumes of the project the services mount.
  
  modelstring | nullrequired
  Its name in the model. Null: made for a path a stateful service mounts with no volume named.
  
  namestringrequired
  Its name in the project.
  
  idstring | nullrequired
  Null: not made yet (to_make).
  
  pattern: ^vol-
  sharedbooleanrequired
  Several services mount it, or one with several instances: every instance of each mounts it at once.
  
  statusto_makeoumadeouthereouexternalrequired
  to_make: the import makes it (a dry run says so of what it would make); made: this import made it; there: an earlier import made it, or a volume of its name was there; external: the model names it external, and the project has it.
  
  used_bytableau destringrequired
- secretstableau deobjectrequired
  The secrets of the model that services are granted.
  
  modelstringrequired
  Its name in the model.
  
  namestringrequired
  The project's secret that holds it: the model's name, with each character a secret's name does not take written as an underscore.
  
  therebooleanrequired
  Whether the project has it. An import (not a dry run) with one that is not there is refused 404 secret_not_found.
  
  used_bytableau destringrequired
- left_outtableau deobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilestableau destringrequired
- absenttableau destringrequired
  The project's services that the model does not have: kept as they are.
- deploystring | nullrequired
  The deploy the import made (GET /v1/deploys/{id}). Null: a dry run, or nothing would get a version.
  
  pattern: ^dpl-
}
accountsoptionaltableau deobject
With sole_owner: the accounts the user is the only owner of.
- idstringrequired
  pattern: ^acct-[0-9a-hjkmnp-tv-z]{16}$
- namestringrequired
}

403

The credential may not do this. needs_api_key: a sandbox token cannot do this. spend_limit_reached: a spend limit was reached. secret_host_not_allowed: a secret would be sent to a host it may not go to: by egress.inject, or as image_pull_secret to the image's registry (param says which; allowed_hosts beside error says where it may go). account_share_reached: its account holds as much of this node's data drive as one account may (drive.accounts of GET /internal/node), and has not the room for the sandbox's memory and a gigabyte to write. Nothing was made.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

404

Something the request names does not exist. snapshot_not_found: no such snapshot; template_not_found: no such template; volume_not_found: a volume named in volumes does not exist; secret_not_found: a secret named in egress.inject, or the one image_pull_secret names, does not exist.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

409

The state of something stands in the way. name_taken: the name is taken; volume_in_use: a volume in volumes that is not shared is another sandbox's; duplicate_volume: a volume is listed twice in volumes; mount_path_taken: two volumes in volumes have one path; too_many_volumes: volumes has more that are not shared than the sandbox's machine has spare drives (eight; two for one made from a template or a snapshot of before there were eight); snapshot_lost: the snapshot's status is lost; no_project_address: project_network was asked for, and the node has no network of the project, or no address of it left to spare; command_lost: the command went away while the call waited for it; sandbox_failed: the sandbox could not be started: the message says why (its image cannot be pulled, for one); idempotency_key_reused: the key was used with another body; idempotency_in_progress: the first request with the key is still running. checkpoints_unavailable (param checkpoint): checkpoint is on, and this node takes no checkpoints (it does not copy its disks to an object store, or its memory is not in layers).

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

503

Not available. not_served_here: egress rules were given, and this node cannot put rules in force (it has no nft); or project_network was asked for, and this node puts no sandbox on a project's network; or the sandbox is to be made from an image the node has no template of, and this node fetches no images (image_pulls of GET /internal/node says why; param is image); or key_missing: this node is keyed (src/seal.rs) and does not hold the key of the project whose it is, or the platform's (the message says which): the control plane gives it, and the same call is made again (Retry-After); or unavailable: a volume in volumes could not be attached in time, and the same call is made again (Retry-After): the guest's mount of it did not finish within 60 s (a Drive whose blocks do not come: its object store away, or its fetcher out of reach), or it is still being taken off the machine after such an attach, or it is a Drive that comes block by block and nothing answers for its blocks yet.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

504

The caller went away. caller_gone: the caller hung up.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$

default

Any other failure, in the same shape. internal (500): the node failed; the message says no more, and the node's log has the reason under the request's id. unavailable (503, retryable): no_capacity, every network slot of the node is in use; memory_full, a machine the call has to start (made, woken, booted from its disk, resumed, rolled back, built) does not fit in the host's memory beside what the machines that run on it are promised, and nothing paused or idle could be put to sleep to make room for it (memory of the node); drive_full, the call would have a template built and the node's data drive has no room for one (drive of the node); unavailable, the node is shutting down, the sandbox was still starting after 10 minutes, or it did not answer, or it is being moved to this node (with Retry-After: 1); fenced, the node's lease fences the sandbox (Node.lease). moved (409): the sandbox was moved to another node, which to names.

JSON

errorobjectrequired
- typestringrequired
  The kind of failure. It decides the status: invalid_request 400, unauthenticated 401, forbidden 403, not_found 404, conflict 409, too_large 413, internal 500, bad_gateway 502 (the preview listener, the egress proxy, and a takeover that could not bring its sandbox), unavailable 503, timeout 504.
- codestringrequired
  Which failure. The top-level x-error-codes table of this document says what each one means.
- messagestringrequired
  For people. English.
- paramstring | nullrequired
  The field or query parameter at fault, when there is one.
- retryablebooleanrequired
  True when the same request may succeed later without anything else changing.
- request_idstringrequired
  The X-Request-Id of the response it is in, also when that response is a replay for an Idempotency-Key.
  
  pattern: ^[A-Za-z0-9._\-]{1,64}$
- docs_urlstring | nullrequired
  The node's --docs-url with the code appended, or null.
}
allowed_hostsoptionalarray | null
With secret_host_not_allowed: the hosts the secret may go to, as the secret has them; null where it was given none.
tooptionalstring | null
With moved and sandbox_moved: the node the sandbox was released to, as the control plane named it, or null.
epochoptionalinteger
With moved and sandbox_moved: the epoch the sandbox was released at. With wrong_epoch: the epoch this node holds it at, or released it at.

format: int64 · minimum: 1
offsetoptionalinteger
With sandbox_moved: the position in the command's output the call, stream or terminal had reached (a stream's last event's id): read on from it where the sandbox went (Last-Event-ID, or from).

format: int64 · minimum: 0
exec_idoptionalstring
With sandbox_moved of POST …/run: the id of the command the call started and waited for, which goes on where the sandbox went: wait for it there through the control plane with GET …/exec/{exec_id}?wait_seconds= once the move is over. The same call made again starts the command a second time, unless it comes with the same Idempotency-Key.
disk_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the disk as of the sleep; null where it did.

minimum: 0
memory_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the memory image of that sleep; null where it did.

minimum: 0
drives_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the sandbox's Drives as they are (slice D2); null where it did, or where it has none.

minimum: 0
image_msoptionalnumber | null
With copy_behind: how long the release waited for the store to hold the image the sandbox's disk is over (its node copies a disk before its template's image is there); null where it did.

minimum: 0
imageoptionalstring
With image_missing: the id of the image the object store does not have, as the disks over it and a template's disk_image name it.

pattern: ^[A-Za-z0-9_-]{1 128}$
buildoptionalstring
With build_missing: the build of Firecracker that wrote the sandbox's memory, which this node does not keep.

pattern: ^[0-9a-f]{16}$