Copy a running sandbox

Makes count sandboxes that go on from this instant, memory, processes and disk, each with its own id, hostname and network. Either all are made or none is left. The copies have the original's settings; shared volumes come with them, a volume that is not shared stands in the way. Wakes the sandbox.

On a node that copies its disks to an object store, a copy's disk goes there whole before anything written to it afterwards counts as copied. That takes what the original's disk holds over what the node's link carries for such copies: measured on a development machine against a store 33 ms away, 1 GiB in 2 s and 4 GiB in 8 s on a node where nothing else is written, 4 GiB in 23 s beside ten disks written at full speed (a quarter of the node's connections are for such copies while other disks have something to send). Such copies take turns by owner (X-Sandbox-Owner; on a node that belongs to no control plane every sandbox has the same owner), and inside an owner the one that was made first goes first: eight copies of 2 GiB each from one call are there one after the other, the first after 5 s and the last after 35 s, and another owner's copy of 256 MiB made a second later is there after 1.3 s and does not wait for them. Until its disk is there a copy is not in the store at all: a host that is lost takes the copy with it. And for that long the copy's writes to its disk wait, from 0.9 s after the first one; reads, and everything that does not write to the disk, go on.

Takes write.

POST

https://api.glac.ai/v1/sandboxes/{id}/fork

Autorizzazione

apiKeyHTTPrequired

Parametri di percorso

idstringrequired
A sandbox's id (sbx-…) or its name.

Parametri di intestazione

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

Corpo della richiestaJSONfacoltativo

countoptionalinteger
How many copies.

maximum: 64 · minimum: 1 · default: 1

Returns

201

The copies, in the envelope of a list.

JSON

dataarray diobjectrequired
The copies, in order. A copy of a sandbox named build is named build-1, build-2, … (the next numbers that are free); copies of a sandbox without a name have none.
- idstringrequired
  sbx- and 16 characters; valid as a DNS label.
  
  pattern: ^sbx-[0-9a-hjkmnp-tv-z]{16}$
- awake_portsarray diintegerrequired
  The ports whose upgraded connections keep it awake, and by which (with its requests and calls) alone it is idle (SandboxCreate); empty for a sandbox that is idle as any is.
  
  maximum: 65535 · minimum: 1
- connection_idle_secondsinteger | nullrequired
  How long a connection on one of awake_ports may carry nothing before the node closes it (SandboxCreate); null: never for that.
  
  minimum: 1
- awake_connectionsintegerrequired
  The connections on its awake_ports open now: while there is one, it is awake (awake_because says so) and is not put to sleep by the idle rule.
  
  minimum: 0
- start_commandrequired
  How its start command runs, how often it was started again in its machine after it ended, and how its last run ended, as its guest said last (once a second while its machine runs: src/restarts.rs). The node has the guest start it again in the same machine, with its disk and volumes as they are, for an instance that is its owner's state (a key's, a stateful service's: a database's), once its command is up; an instance of an app's group is retired instead, and another takes its place; any other sandbox's start command is left as it ended. Null where its guest has said nothing of it: it has none, it has not begun (a stateful service's waits for its volumes), or its machine has not run since the node knew to ask.
  
  Uno dei seguenti:
  SandboxStartCommand
  statusstringrequired
  running: a run of it is under way (or what it left behind still holds its output); restarting: it ended, and is started again at restarting_at; exited: it ended, and nothing starts it again.
  
  restartsintegerrequired
  How often it was started again in its machine since the sandbox was made, across the boots of its machines.
  
  format: int64 · minimum: 0
  last_exitrequired
  How its last run ended; null where none has.
  
  Uno dei seguenti:
  object
  null
  restarting_atstring | nullrequired
  While restarting: when its next run begins, by its guest's clock (a machine asleep then starts it as it wakes). Null otherwise.
  
  format: date-time
  null
- devtoolsobject | nullrequired
  Of a sandbox of a browser's image (one with the label sbx.devtools, the port of its browser's DevTools protocol): the browser's own address, as the node asked it (/json/version) when it built the image's template. The browser is the template's, the same in every sandbox made from it, and this goes with the sandbox wherever it goes. A client that takes nothing but a WebSocket's address connects to path at the signed link of port. Null for any other sandbox.
  
  portintegerrequired
  maximum: 65535 · minimum: 1
  pathstringrequired
  /devtools/browser/<the browser's id>.
  
  pattern: ^/devtools/browser/[A-Za-z0-9-]{1,64}$
- proxyrequired
  Its own proxy (SandboxCreate's proxy): its address and the user name it is asked with, never its password. Null where it has none.
  
  Uno dei seguenti:
  SandboxProxy
  urlstringrequired
  http://host:port: the proxy's address, without the credentials.
  
  usernamestring | nullrequired
  The user name it is asked with; null where it is asked with none.
  
  null
- image_digeststring | nullrequired
  The image its disk was made of, by the digest of its manifest (or list of manifests) as its registry named it when its template was built (Template.image_digest): what a tag named then. A tag that is moved since makes another image of the sandboxes made after it (a newer template), and this one's stays. While its template is being built (starting): the image the build is of, where the create knew it (a tag found to name a newer image than the template there holds, built by that digest), else null; and null where the template does not say (one built from a disk file, or before templates said so).
  
  pattern: ^[A-Za-z0-9]+:[0-9A-Fa-f]{32,}$
- appstring | nullrequired
  For an instance of an app, one of those the node makes and deletes by the app's requests (PUT /internal/apps/{key}): the app, by the key of its template, as the node's inventory says it. Null for any other sandbox, a keyed instance of an app among them (its metadata say its app and its key). A control plane shown an instance first in the answer to a call keeps it out of its edges' table by this, as it keeps one its node's inventory lists.
- ipv6string | nullrequired
  Its own public IPv6 address, for its whole life: what it sends over IPv6 leaves from it, untranslated, and what comes to it is let in as inbound says. Given when it is made, on a node with a pool of addresses; kept through sleep, snapshot and move; a fork, or a sandbox made from a snapshot, has one of its own. Null: IPv4 alone (its node has no pool, or its template's agent is from before addresses of their own).
- inboundarray diobjectrequired
  The ports open to the internet at ipv6, each with the sources it is open to, in the order of protocol and port. Closed by default: empty.
  
  protocoltcpoppureudprequired
  portintegerrequired
  maximum: 65535 · minimum: 1
  fromarray distringrequired
  The IPv6 prefixes it is open to (2001:db8::/32; a single address as the prefix of 128 bits it is, 2001:db8::7/128; ::/0 for everybody), each once, in their order.
- checkpointrequired
  Its checkpoints while it runs (SandboxCreate's checkpoint), and how they go; null where it has none.
  
  Uno dei seguenti:
  CheckpointStatus
  every_secondsintegerrequired
  The setting.
  
  maximum: 600 · minimum: 1
  last_atstring | nullrequired
  The instant of its newest checkpoint in the store (when its machine was paused for it); null before the first.
  
  format: date-time
  behind_secondsnumberrequired
  While it runs, how much longer ago than every_seconds its newest checkpoint was taken. It rises while the next one is on its way and drops when that one is in the store: while its checkpoints keep up it stays 0 or under what one takes to reach the store; past an interval, one took longer than an interval, and it grows on while it writes faster than they go to the store (or the store does not answer). 0 while it sleeps.
  
  minimum: 0
  bytes_per_secondintegerrequired
  What its checkpoints sent of late, bytes a second (compressed).
  
  minimum: 0
  stored_bytesintegerrequired
  What the store keeps of its newest checkpoint: its memory as it was, the state of its devices, and its disk's blocks the store had in no other copy then. Billed as a sleeping sandbox's state while it runs.
  
  minimum: 0
  errorstring | nullrequired
  Why the last checkpoint was not taken or not sent, in a sentence; null when it was.
  
  null
- secret_envarray distringrequired
  The names of the variables of secret_env it was made with, in order; never a value. Empty for one made with none.
- objectstringrequired
- namerequired
  The name the caller gave it, or null.
  
  Uno dei seguenti:
  Name
  null
- statusstringrequired
  Information: a caller need not look at it before a call. starting: its image is being pulled and built, and calls that need it wait. sleeping: memory saved, nothing running (also shown for a sandbox that has only its disk left, and for one that is paused in the node's memory: sleep_tier says which); the next call that needs it wakes it. failed: it could not be built or woken, or its record on the node could not be read after the node's host went down, and calls that need it answer 409 sandbox_failed. The answer of a call that changes it (create, sleep, restart, restore) shows the status that call left.
- sleep_tierrequired
  How a sleeping sandbox sleeps; null for every other status. paused: its machine stands still in the node's memory, with its processes and connections (a node with the pause tier on pauses an idle sandbox instead of saving it), and a call resumes it in about a millisecond; the memory its machine holds is metered as a running sandbox's is (usage.memory_bytes, memory_gib_seconds), and its CPU is not. saved: its memory and the state of its devices are saved on the node, and nothing runs; a call wakes it from them in a few milliseconds. disk: only its disk is left (its machine ended by itself, the node's daemon ended without putting it to sleep, or its memory could not be kept); the next call that needs it boots it from the disk, and what ran is gone. POST /v1/sandboxes/{id}/sleep saves a sandbox, paused or running.
  
  Uno dei seguenti:
  string
  null
- failurestring | nullrequired
  Why the sandbox is failed, in a sentence for people; null otherwise. It names nothing of the node: no path, no line of a tool's log. Of a registry that refused the credentials it was asked with, it has the registry's own words, with the credentials cut out of them.
- failure_coderequired
  Why the sandbox is failed, for programs; null otherwise. image_not_found: the image is not in its registry, or is not public (a registry that wants a login says no more than that to a create that names no credentials). image_pull_failed: the registry could not be reached or did not hand the image out, or the tool that fetches was stopped at a limit of the node's (failure says which). registry_auth_failed: the registry refused the credentials the create named (image_pull_secret); failure has what the registry said. image_unpack_failed: the image does not fit the disk, is larger than the node takes (failure has the numbers), or cannot be unpacked. invalid_image: the registry is at an address on the node or in a private network, or the image cannot be started as asked (no ENTRYPOINT or CMD for start: true, labels that ask for what cannot be done). boot_failed: the machine made from the image did not start, or its start command did not come up (then failure says what its ready check got and what it printed last). no_capacity: the node had no room. memory_full: the host's memory had no room for the machine its template is built in, or for its own. drive_full: the node's data drive filled while the image's template was being built. record_lost: the sandbox's record cannot be read; its files are kept on the node, but it cannot be started, only deleted. recovery_failed: the sandbox's startup recovery could not finish; its files and recovery intent are kept on the node, and it cannot be started, only deleted. start_failed: anything else; the node's log has it.
  
  Uno dei seguenti:
  string
  null
- imagestring | nullrequired
  The OCI image reference the sandbox goes back to. Null only on a node whose base template was built from a disk file.
- snapshotstring | nullrequired
  The id of the snapshot whose state the sandbox last took: the one it was created from or restored to. Null for a sandbox made from an image. Not cleared when that snapshot is deleted, and for a fork it names the fork's own temporary snapshot, which is gone by the time the call returns.
  
  pattern: ^snap-[0-9a-hjkmnp-tv-z]{16}$
- metadatamappa distringrequired
  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).
- volumesarray diobjectrequired
  pathstringrequired
  Where it is mounted.
  
  volumestringrequired
  The volume's id (never its name).
  
  pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
  namestring | nullrequired
  The volume's name, if it has one.
  
  read_onlybooleanrequired
  sharedbooleanrequired
  True for a shared volume (served by the node over NFS), false for one that is this sandbox's alone (a block device).
  
  kindoptionalstring | null
  The volume's kind (Volume.kind): a Drive goes with the sandbox when it moves to another node (slice D2), any other kind keeps it where it is. Null for one this node does not have.
  
  view_ofoptionalobject | null
  Of a read-only view of a version of a Drive (slice D7: volumes with version): the Drive, and the version. The view is the sandbox's alone, and goes with it.
  
  drivestringrequired
  pattern: ^vol-[0-9a-hjkmnp-tv-z]{16}$
  versionobjectrequired
  A version of a Drive in the object store (slice D4, a root of its table of versions), as a snapshot of it says it (slice D7): what a fork, a restore and a read-only view are made of.
  
  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).
- public_portsarray diintegerrequired
  Ports whose preview URL needs no signature and no token. Duplicates are kept as given.
  
  maximum: 65535 · minimum: 1
- public_ports_exceptarray | nullrequired
  Every port but these is public as well, as if it were in public_ports (SandboxCreate); null where that is not said. A sandbox the control plane's E2B compatibility makes has [49983]: its ports are public as E2B's are, envd's port behind the sandbox's token.
- egressobjectrequired
  A sandbox's egress rules, as they are stored: what it may reach, what it may ask of a host, and which of its requests get a secret added. Always there; a sandbox without rules has default allow and four empty lists, and its traffic takes the path it would take without rules. A connection or a packet that deny speaks of is refused; one that allow speaks of passes; anything else gets default. A host in inject counts as allowed, and so does a host in http, for the requests its entry allows. Whatever the rules say, a sandbox reaches neither the node, nor other sandboxes, nor private ranges, nor the metadata addresses of clouds.
  
  A host name is matched against the server name of a TLS handshake and the Host header of an HTTP request, on any port, and against the sandbox's DNS questions, which the node answers itself for a sandbox whose rules can refuse a name (for a refused name the answer is REFUSED). A connection that names an allowed host goes to an address the node has for that name, whatever address the sandbox was connecting to. A TCP connection that is neither TLS nor HTTP passes to an address the rules list, or to one the node gave the sandbox as that of an allowed name. UDP and every other protocol go by address only. Under default: allow a deny list is not a wall: anything allowed that relays traffic gets around it.
  
  defaultallowoppuredenyrequired
  What happens to what neither list speaks of.
  
  allowarray distringrequired
  Reached under default: deny. Empty under default: allow.
  
  maxLength: 300
  denyarray distringrequired
  Never reached, whatever allow says.
  
  maxLength: 300
  httparray diobjectrequired
  The requests the sandbox may send to a host, by method and path. Methods are shown in capitals, each once; the rest as it was given.
  
  hoststringrequired
  A host name, or *. and a name. Not an address.
  
  maxLength: 300
  allowarray diobjectrequired
  The requests that pass. A host that is to get none goes in deny.
  
  methodsoptionalarray | null
  Methods, as tokens; kept in capitals. A request's method is compared as it was sent, so get is none of them. CONNECT cannot be allowed.
  
  pathsoptionalarray | null
  Patterns. A pattern is a path: it begins with /, has no ? and no #, and is compared with the whole path of the request, which is its target before the ? (the query is not judged). * stands for any run of characters, / included, and nothing else is special: /repos/* is everything under /repos/ and not /repos. Case matters. Both are compared in one form: escapes of unreserved characters are decoded (%7E is ~), other escapes are kept with their digits in capitals, bytes outside ASCII are escaped. An encoded slash stays one and is not /; a pattern can contain %2F to allow exactly that (/@types%2Fnode). A path that hosts could read as another path has no form and matches no pattern (a rule without paths still has it): one with a segment that is . or .. after its escapes are decoded, once or more often, with \ and an encoded slash read as /, with what follows a ; in a segment cut off and the spaces at a segment's ends dropped; one with a malformed escape, a #, a control character, bytes that are no UTF-8, or a character that folds into ., / or \ (U+FF0E, U+FF0F, U+FF3C, U+2215, U+2044, U+2024); one of more than 8192 bytes. Such a request is answered 400 malformed_request.
  
  injectarray diobjectrequired
  Headers the node adds to the sandbox's HTTPS requests to a host.
  
  hoststringrequired
  A host name, or *. and a name. Not an address.
  
  maxLength: 300
  headersmappa distringrequired
  Each header's name and value. In a value, ${secrets.NAME} stands for the secret of that name (PUT /v1/secrets/{name}), which has to be one that may go to host (its allowed_hosts; 403 secret_host_not_allowed otherwise); the sandbox object shows the reference, never the secret. Headers that say where a request goes or where it ends (Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, Expect) cannot be set.
  
  deny_portsoptionalarray diinteger
  Ports no connection reaches, TCP or UDP, wherever it goes and whatever else the rules say: refused first, by the packet filter, and never handed to the proxy. Shown only where the rules close any. A control plane closes a Browsers session's mail and mining-pool ports so.
  
  maximum: 65535 · minimum: 1
- sleep_after_secondsnumber | nullrequired
  The sandbox sleeps after this long idle. Null: never by itself. At least 1 where a caller set it; an instance of an app has what its app says (sleep_after_ms of PUT /internal/apps/{key}), which may be less.
  
  minimum: 0
- expires_atstring | nullrequired
  When the sandbox deletes itself (or what on_expiry says). Null: never.
  
  format: date-time
- on_expirydeleteoppuresleepoppureholdrequired
  What expires_at does when it comes: delete, the sandbox is deleted (the default); sleep, it is put to sleep whatever goes on in it and kept, its expires_at null from then on; hold, the same, held asleep (held_asleep set). The control plane's E2B compatibility gives sleep or hold to a sandbox whose time being up pauses it.
- held_asleepbooleanrequired
  Asleep and not woken by requests (E2B's paused sandbox, which the control plane's E2B compatibility holds so between its pause and its connect): while it sleeps, a request to one of its ports does not wake it, and the preview listener answers 502 sandbox_paused in its place (x-preview-ingress). A call of the API wakes it as ever, and so does its own timer; a request that comes while it is awake goes on to it.
- sleep_notice_msinteger | nullrequired
  How long before the idle rule puts it to sleep the programs connected to its guest's /run/sbx/awake are told, in milliseconds (SandboxCreate); null: not told.
- sleep_hold_max_msintegerrequired
  How long its guest's holds keep it up at the most, in milliseconds (SandboxCreate): its own, or the node's. While held, awake_because says so.
  
  minimum: 0
- suspend_after_msintegerrequired
  How long the pause tier holds it paused before it sleeps for real, in milliseconds (SandboxCreate): its own, held to the node's --pause-max-seconds; the node's where it says none.
  
  minimum: 1000
- wake_daily_atstring | nullrequired
  The time of day, in UTC, at which the node wakes it every day while it rests (SandboxCreate); null: none.
  
  pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
- delete_after_idle_msinteger | nullrequired
  After how long asleep the node deletes the sandbox, in milliseconds, counted from idle_since: a sandbox that is woken counts again from its next sleep. Null: never for that (the default); the sandbox stays until it is deleted, or until its expires_at. A sandbox that does not sleep by itself (sleep_after_seconds null) counts the sleeps it is put to (POST /v1/sandboxes/{id}/sleep, a restart of its node). Not while it is frozen (its owner's spend limit): a freeze keeps it with its data, and once let go of, the sleep it is in counts from then.
  
  format: int64 · minimum: 1000
- idle_sincestring | nullrequired
  When its current sleep began, while status is sleeping: when its machine was paused or put to sleep, or found to have ended. One that was running when its node stopped sleeps from the moment its node was started again; one that was frozen, from the moment it was let go of. Null while it is not asleep.
  
  format: date-time
- limitsobjectrequired
  The shape of the machine: what its create asked for in limits, each part it did not give the node's base template's; a sandbox made from a snapshot or a template has that one's. The disk's size is the node's, for every sandbox.
  
  vcpusintegerrequired
  Virtual CPUs.
  
  minimum: 0
  memory_bytesintegerrequired
  Memory the machine has.
  
  format: int64 · minimum: 0
  disk_bytesintegerrequired
  The size of the root disk. 0 while a sandbox is starting and has no disk yet.
  
  format: int64 · minimum: 0
- guest_mitigationsbooleanrequired
  Whether the guest kernel keeps its mitigations against speculative execution (guest_mitigations at creation).
- tmpdiskoppurememoryrequired
  Where its /tmp is (tmp at creation): on its disk, or a tmpfs in its guest's memory, which is billed as memory and is gone when the sandbox starts again from its disk. One made from a snapshot has the snapshot's sandbox's.
- created_atstringrequired
  format: date-time
- booted_atstring | nullrequired
  When the machine last started from nothing: at creation, and after every restart from its disk. A sleep and a wake do not change it.
  
  format: date-time
- last_active_atstring | nullrequired
  The last activity the node saw: a call, a packet on its link, its guest computing (more than 2% of a core over sleep_after_seconds, by the guest's own count where the host saw more than that; by the host's count for a template from before guests said what they computed), noted when the node looks.
  
  format: date-time
- awake_becausestring | nullrequired
  Why a running sandbox has not been put to sleep, in a few words of prose. Null unless status is running. An instance of an app says what the node gave it: a request in its hand, a call in flight, a request that ended less than its sleep_after_seconds ago, or that its app's floor keeps it awake. One that a packet on its project's network woke, and that nothing else has kept awake since, says so and which packet it was: woken by a packet: TCP from 10.64.0.7:41594 to port 5432 [S] …. Connections inside its project keep no sandbox awake: what comes over them while it sleeps is the node's hold's (Node.hold).
- usageobjectrequired
  What the sandbox has used and uses.
  
  proxy_sent_bytesintegerrequired
  Bytes the sandbox sent through its own proxy since it was created (proxy): what went into its tunnels, counted as the proxy was given each byte (the requests for the tunnels not among them). 0 for one that never had one.
  
  format: int64 · minimum: 0
  proxy_received_bytesintegerrequired
  Bytes that came back to the sandbox through its own proxy since it was created, counted as each was taken from the proxy, whether or not the sandbox's end of the connection was still there to take it (what the proxy counts it sent).
  
  format: int64 · minimum: 0
  awake_secondsnumberrequired
  How long a machine of the sandbox has run since it was created, to the millisecond: its time awake. Not while it sleeps, nor while the pause tier holds its machine paused. The same milliseconds its memory is counted over (memory_gib_seconds). The node's books count it hour by hour (awake_ms of a slice of GET /internal/inventory).
  
  minimum: 0
  egress_refused_requestsintegerrequired
  How many of the sandbox's HTTP requests the node has read and not passed on since the sandbox was created: the ones its own egress rules refuse, the ones it could not read in one way, and the ones that came while its owner's sandboxes had their share of the proxy's connections (the answers of x-egress-proxy with a status of 400 or 403, 502 secret_missing and 503 egress_connections_full). Counted once a second. Each is also a line of the node's log, with the id the answer carried, the method, the host and the path, without the query; of one sandbox's, at most 30 a minute are written.
  
  format: int64 · minimum: 0
  cpu_secondsnumberrequired
  CPU time the sandbox's machine has used since the sandbox was created: its vCPUs and the devices that serve them. Time the host spends waiting on the guest's behalf with a CPU is left out: the hypervisor polling for a halted vCPU to be woken, and the block device looking for the next request. What is left out never exceeds what has been counted: at least half of the CPU time the machine's process used is the sandbox's.
  
  minimum: 0
  memory_gib_secondsnumberrequired
  The memory the sandbox holds on the host by itself (memory_bytes), rounded up to 128 MiB steps, integrated over the time the sandbox was awake or paused (sleep_tier paused): GiB times seconds.
  
  minimum: 0
  memory_bytesintegerrequired
  Memory the host holds for this sandbox alone now: what the guest has written of its template's memory, memory the template never had, and the VMM's own. Pages of the template that the guest has only read are shared by every sandbox of the template and not counted. Of a paused sandbox, what its machine holds standing still; 0 while the sandbox sleeps otherwise.
  
  format: int64 · minimum: 0
  disk_bytesintegerrequired
  Bytes the root disk takes on the node now.
  
  format: int64 · minimum: 0
  egress_bytesintegerrequired
  Bytes the sandbox has sent to the internet since it was created: what it sent itself, and what went out to visitors of its preview URLs.
  
  format: int64 · minimum: 0
- host_failurerequired
  What the sandbox last lost to the host it is on, and why (cause): its memory when the host went down hard (power, a kernel that gave up), as the node found it when it came back; or its memory when the node was started again with another Firecracker than had saved it, and the sandbox was then used. Null for a sandbox that lost nothing: one that never went through either, and one that was asleep with everything it needs on the host's disk, which wakes as it always does on a node that is what it was. It stays as it is until the next such loss.
  
  Uno dei seguenti:
  SandboxHostFailure
  atstringrequired
  When the node found the sandbox like this. With cause hard_stop that is when the node came back; the host went down some time before.
  
  format: date-time
  causestringrequired
  hard_stop: the host went down without warning (power, a kernel panic). node_changed: nothing went down. The sandbox's memory, or the memory of the snapshot it was created from or rolled back to, was whole, and had been saved by a build of Firecracker that the host does not keep (a build it keeps wakes what it saved: Node.firecrackers; detail names the build), or with other settings for the machine's devices than the node starts machines with now (after an upgrade of the node, for one). A saved machine is loaded only into what saved it: anything else would run its guest against devices that are not the ones it had, which damages what it reads and writes without an error anywhere. The node keeps such memory until the sandbox is next used, so that a node that is started again with what saved it wakes the sandbox as it was; at the first use on a node that cannot load it, the memory is given up and this is set. load_failed: nothing went down, the memory was whole and was one this node loads, and it could not be brought back all the same (after a change of the host's kernel, for one: detail names the kernel the memory was saved under and the one that was to load it). Memory is given up for this on evidence only: the node's Firecracker refused to load it; the process that was to load it ended over the load; the machine ended as soon as it was loaded; the machine was loaded, did not answer, and could not be saved again; or the machine was loaded, stayed alive and did not answer, a second time five minutes or more after the first with no wake that worked in between. A wake that fails before anything was loaded leaves the memory as it was, and so does a first silence, and every silence in the five minutes after it: those calls are answered 503 unavailable and can be made again. The call that finds the memory gone is answered by the machine that is then started from the disk. rollback_interrupted: the node stopped during a roll-back. Its forced disk replacement was replayed before this sandbox was served; its previous memory was discarded, and it starts from the snapshot's disk. The replacement intent stays until the loss record and the stopped block are on disk. moved: the sandbox was moved to this node from another (POST /internal/sandboxes/{id}/takeover) and came without its memory, because the store had no memory image of the very state its disk was brought back to: it had woken since its last sleep, or was running when the other node's host was lost, or the image could not be read (detail says which). Its disk is that state (disk restored).
  
  memorystringrequired
  lost: what the sandbox had in memory is gone, its processes included. With hard_stop: either its machine was running, or it had gone to sleep so shortly before that its memory was not yet whole on the host's disk; a memory image that is not whole is never woken. With node_changed: the memory was whole and was not loaded. With load_failed: the memory was whole, and loading it failed. With moved: no image of its memory could be loaded over the disk it came with.
  
  diskstringrequired
  What the sandbox's disk is now. whole: nothing went down, and the disk lost nothing (node_changed: it is as it was when the memory was saved; load_failed: it has, besides, whatever a machine that was loaded and did not answer wrote before it was ended). unverified: the disk on the host, which was not known to be whole: the guest's file system replays its journal when the sandbox starts, and what was written in the last half minute before the host went down may be missing or incomplete, whether or not the guest had been told it was written. restoring: the node copies disks to an object store, and the sandbox's disk is being brought back from the copy there; calls that need the sandbox answer 503 unavailable until that is done. restored: the disk is the copy the object store had, a state the disk was really in, as of disk_as_of.
  
  disk_as_ofstring | nullrequired
  With disk restored: the moment the disk went back to. What was written after it is gone. Null otherwise.
  
  format: date-time
  detailstringrequired
  The same in a sentence for people.
  
  null
- project_addressstring | nullrequired
  Its address on its project's private network: where the project's other sandboxes on that network reach it, and what they see it as, whichever slot of the node it runs in. Null for a sandbox that is on no project's network. Given by whoever tells the node of the network (setProjectNetwork), or taken by a create that said project_network: true.
  
  pattern: ^10\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])(\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){2}$
- regionrequired
  The region of the node that holds it, as the node was told (--region): where a control plane placed it. Null on a node that is in no region.
  
  Uno dei seguenti:
  string
  null
- usable_atstring | nullrequired
  Where its disk came back from the object store (a restore, a move to this node, or a sandbox made here from a snapshot taken on another node, whose disk is in the store), the moment it could answer: its node had it and, for a disk filled as it is read, something listened for the blocks not here yet. Null for a sandbox whose disk was made on its node. Each such arrival starts the four fields over.
  
  format: date-time
- hydrated_atstring | nullrequired
  The moment every block of its disk was on its node after it came back from the object store; null until then, and for a sandbox whose disk was made there. Never before usable_at; set once for each arrival (sandbox.hydrated says so).
  
  format: date-time
- hydrated_bytesinteger | nullrequired
  How many bytes of its disk are on its node, of total_bytes, while it fills after it came back from the object store (a block brought ahead of the guest's first read counts); total_bytes once it is all there. Bytes, not files: what a few large files that come last hold shows as what is left. Null as total_bytes is.
  
  format: int64 · minimum: 0
- total_bytesinteger | nullrequired
  How many bytes its disk brings from the object store: its own, and its image's where its node did not have the image and it comes block by block too. Null for a sandbox whose disk was made on its node, and in the moment before its node has counted them.
  
  format: int64 · minimum: 0
- disk_writesrequired
  What its disk has written today (UTC), against the day's share at full speed: past the share its disk takes writes slowly until the day ends, and no write fails. Null on a node that does not copy its disks to an object store, which counts nothing and slows nothing, and for a static instance (SandboxInternals.static), whose disk is not copied.
  
  Uno dei seguenti:
  SandboxDiskWrites
  today_bytesintegerrequired
  Bytes written since the day began (UTC).
  
  format: int64 · minimum: 0
  checkpoint_copy_bytesintegerrequired
  Of today_bytes, what its checkpoints' copies wrote to the host's disk (0 while the store takes each copy before the host writes it out). Where its disk takes writes at a limited rate, its next checkpoint waits until these bytes have gone at that rate.
  
  format: int64 · minimum: 0
  full_speed_until_bytesinteger | nullrequired
  The day's share at full speed: 100 GiB unless the node is told otherwise (--disk-write-full-gib-per-day). Null: the node slows nothing.
  
  format: int64 · minimum: 0
  limitedbooleanrequired
  Past the day's share: the disk takes writes at 2 MiB a second (--disk-write-after-mib-per-second), or at the sandbox's own limit where that is lower, until the day ends.
  
  limited_untilstring | nullrequired
  When the day ends and the disk takes writes at full speed again; null when it is not limited.
  
  format: date-time
  null
- app_idoptionalstring
  Of an instance of an app of a control plane's (SandboxCreate.instance_of: an app of the Sandboxes product, control/src/sandboxes.rs): the app, as the control plane names it, for the sandbox's whole life. Not there for any other sandbox.
- version_idoptionalstring
  With app_id: the version of the app its create asked for, as the control plane names it. Through a control plane, the version of the image it was made of (image_digest): a tag moved under the app is a version of its own.
- keyoptionalstring
  With app_id: what it is found by among the app's instances, its name, or its id where it has none.
- envoptionalmappa distring
  The sandbox's environment variables and their values. Absent (not null) when the caller is a sandbox token with none of the scopes exec, files and tty: the values are often credentials, and a token for the sandbox's links is not one for them.
- initoptional
  What its PID 1 is (init at creation): systemd, its image's own systemd (a whole system), or null, the platform's init. One made from a snapshot, or a fork, has the snapshot's sandbox's. A whole system has a machine ID of its own (/etc/machine-id, and D-Bus's copy, /var/lib/dbus/machine-id), given when its machine is made (a clone of a template or a snapshot, a fork, a boot from a snapshot's disk) and kept from then on, through sleeps, wakes, moves and boots from its disk; its journal is filed under it (/var/log/journal/).
  
  Uno dei seguenti:
  string
  null
- url_secretoptionalstring
  Signs this sandbox's preview links. Absent (not null) when the caller is a sandbox token.
  
  pattern: ^[0-9a-f]{32}$
- url_patternoptionalstring | null
  The preview URL of a port, with {port} and {signature} to fill in: the signature is the first 12 characters of base32(HMAC-SHA256(key = url_secret, message = the port in decimal)), in the alphabet 0123456789abcdefghjkmnpqrstvwxyz. For a public port (public_ports, or one public_ports_except does not name where it is given), drop -{signature}. Null when the node has no preview domain; absent when the caller is a sandbox token.
}
next_cursornullrequired
Always null.

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_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.
  
  Uno dei seguenti:
  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).
problemsoptionalarray diobject
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
- profilesarray distringrequired
- treatmentsobjectrequired
  How many items of the report have each treatment.
  
  doneintegerrequired
  minimum: 0
  adaptedintegerrequired
  minimum: 0
  ignoredintegerrequired
  minimum: 0
  refusedintegerrequired
  minimum: 0
- itemsarray diobjectrequired
  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).
  
  treatmentdoneoppureadaptedoppureignoredoppurerefusedrequired
  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.
- servicesarray diobjectrequired
  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-
  statuscreatedoppurechangedoppureunchangedrequired
  What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing.
  
  kindserviceoppurejobrequired
  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.
  
  itemsarray diobjectrequired
  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).
  
  treatmentdoneoppureadaptedoppureignoredoppurerefusedrequired
  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
  Uno dei seguenti:
  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.
  
  Uno dei seguenti:
  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.
  
  Uno dei seguenti:
  string
  array<string>
  envmappa distringrequired
  secretsmappa distringrequired
  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
  volumesarray diobjectrequired
  volumestringrequired
  pathstringrequired
  read_onlybooleanrequired
  nocopyoptionalunknown
  There only where it was given as true.
  
  kindstringrequired
  filesarray diobjectrequired
  pathstringrequired
  modeintegerrequired
  uidintegerrequired
  gidintegerrequired
  contentoptionalstring
  secretoptionalstring
  userstring | nullrequired
  working_dirstring | nullrequired
  stoprequired
  Uno dei seguenti:
  ServiceStop
  signalstring | nullrequired
  grace_msinteger | nullrequired
  null
  hostnamestring | nullrequired
  regionsarray distringrequired
  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
  Uno dei seguenti:
  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).
  
  defaultoptionalallowoppuredenyoppurenull
  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.
  
  metadatamappa distringrequired
  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_onarray diobjectrequired
  servicestringrequired
  conditionstringrequired
  networkobjectrequired
  aliasesarray distringrequired
  endpoint_modestringrequired
  drivesoptionalarray diobject
  The Drives its instance mounts (AppCreate.drives): none, [], where it names none.
  
  drivestringrequired
  pathstringrequired
  modestringrequired
  key_drivesoptionalarray diobject
  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.
  
  Uno dei seguenti:
  Runtime
  ulimitsmappa diRuntimeLimitGivenrequired
  sysctlsmappa distringrequired
  tmpfsarray diobjectrequired
  pathstringrequired
  size_bytesinteger | nullrequired
  modeintegerrequired
  dnsobjectrequired
  serversarray distringrequired
  searcharray distringrequired
  optionsarray distringrequired
  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
- volumesarray diobjectrequired
  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_makeoppuremadeoppurethereoppureexternalrequired
  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_byarray distringrequired
- secretsarray diobjectrequired
  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_byarray distringrequired
- left_outarray diobjectrequired
  The services of profiles that are not turned on, which the import does not touch.
  
  namestringrequired
  profilesarray distringrequired
- absentarray distringrequired
  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-
}
accountsoptionalarray diobject
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: the sandbox is frozen because a spend limit was reached; it sleeps, with its data, until the limit is raised. account_share_reached: its account has not the room on this node's data drive for the copies (drive.accounts of GET /internal/node): the snapshot they are made from, or the memory of each 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. sandbox_not_found: no such sandbox.

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. exclusive_volume_attached: the sandbox has a volume that is not shared; sandbox_failed: the sandbox is failed; idempotency_key_reused: the key was used with another body; idempotency_in_progress: the first request with the key is still running; busy: a volume is still behind one of the sandbox's spare drives after an attach that did not get through (its guest's reads of it are held up, a Drive whose blocks do not come), and is taken off it once they end; or the sandbox's guest has a read held up on a Drive it has (its blocks do not come: the message names the Drive and says for how long), until that read ends: the same call is made again in a moment. static_instance: the sandbox is the instance the node keeps of a static spec (GET /internal/static): a copy would be a second of what runs in it.

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}$