--- title: "Create a sandbox" description: "Returns when the sandbox can run commands, with `status` `running`. For an image the node has not built yet it returns at once with `status` `starting`; calls that need the sandbox wait for it, and if the image cannot be pulled the sandbox becomes `failed`.\n\nTakes `write`." --- > Documentation Index > Fetch the complete documentation index at: https://glac.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. Path: Glac API › Sandboxes `POST /v1/sandboxes` Returns when the sandbox can run commands, with `status` `running`. For an image the node has not built yet it returns at once with `status` `starting`; calls that need the sandbox wait for it, and if the image cannot be pulled the sandbox becomes `failed`. Takes `write`. ## Authentication - `apiKey`, http, header `Authorization`, scopes: `write` ## Header parameters - `X-Request-Id` (`createSandbox.header.X-Request-Id`; string, optional) — 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-Key` (`createSandbox.header.Idempotency-Key`; string, optional) — Makes the request safe to send again. See "Idempotency-Key" in the introduction. - minLength 1; maxLength 255 ## Request body _Optional._ - `start` (`createSandbox.start`; boolean, optional) — `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_command` (`createSandbox.start_command`; one of, optional) — 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`. - one of: `string`, `array` - `ready` (`createSandbox.ready`; one of, optional) — 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. - one of: `object`, `object`, `object` - `egress` (`createSandbox.egress`; object | null, optional) — What the sandbox may reach, what it may ask of a host, and which of its requests get a secret added. In force before the sandbox runs anything. A sandbox made from a `snapshot` starts with the rules the snapshot recorded unless this field is given; null then means no rules. - `default` (`createSandbox.egress.default`; string | null, optional) - one of `"allow"`, `"deny"`, `null` - `allow` (`createSandbox.egress.allow`; array | null, optional) - `deny` (`createSandbox.egress.deny`; array | null, optional) - `http` (`createSandbox.egress.http`; array | null, optional) - `inject` (`createSandbox.egress.inject`; array | null, optional) - `deny_ports` (`createSandbox.egress.deny_ports`; array | null, optional) — 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_mitigations` (`createSandbox.guest_mitigations`; boolean, optional) — 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). - `tmp` (`createSandbox.tmp`; string, optional) — 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. - one of `"disk"`, `"memory"`; default `"disk"` - `runtime` (`createSandbox.runtime`; any of, optional) — 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. - any of: `NodeRuntime`, `null` - `init` (`createSandbox.init`; one of, optional) — 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」). - one of: `string`, `null` - `project_network` (`createSandbox.project_network`; boolean, optional) — `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. - `image` (`createSandbox.image`; string, optional) — 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_secret` (`createSandbox.image_pull_secret`; string, optional) — 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 - `snapshot` (`createSandbox.snapshot`; string, optional) — A snapshot's id or name: the sandbox goes on from the instant the snapshot was taken, processes included. - `template` (`createSandbox.template`; string, optional) — 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. - `limits` (`createSandbox.limits`; object, optional) — 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`. - `vcpus` (`createSandbox.limits.vcpus`; integer | null, optional) — Virtual CPUs. - min 1; max 32 - `memory_bytes` (`createSandbox.limits.memory_bytes`; integer | null, optional) — 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`; min 134217728 - `name` (`createSandbox.name`; string, optional) — 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])?$` - `env` (`createSandbox.env`; map, optional) — Environment variables. Names match `[A-Za-z_][A-Za-z0-9_]*`; values hold no NUL byte; at most 256 KiB in all. - `secret_env` (`createSandbox.secret_env`; map, optional) — More environment variables, whose values are secrets: every command started in the sandbox gets them with `env`, and so does its start command (written for it where `env` is, and nowhere else: no value of them is in a template's key or record). No answer shows a value: the sandbox shows their names (`Sandbox.secret_env`). At most 64 variables and 64 KiB, names as `env` takes them, none of them in `env` too (400 `invalid_field`, `param` `secret_env.`); taken when the sandbox is made and not changed afterwards (a PATCH that gives `env` one of these names is refused the same way, `param` `env.`). Not in a snapshot: a sandbox made from one has the ones its own create gives. - `metadata` (`createSandbox.metadata`; map, optional) — 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). - `volumes` (`createSandbox.volumes`; array, optional) — Volumes to mount before the call returns. At most two that are not shared. A sandbox made from a template that holds its start command back (`TemplateBuildRequest.start_after_volumes`) has its start command started once they are mounted, and the call returns when the command is up as the template's `ready` says; so does every boot of it from its disk (a restart, a host that went down), which mounts them first. - `path` (`createSandbox.volumes.path`; string, required) — Where the volume is mounted in the sandbox: an absolute path other than `/`. - `volume` (`createSandbox.volumes.volume`; string, required) — The volume's id or name. - `read_only` (`createSandbox.volumes.read_only`; boolean | null, optional) — Mount it read-only. For a shared volume this is enforced on the node, not in the sandbox. - default `false` - `copy` (`createSandbox.volumes.copy`; boolean | null, optional) — `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` - `version` (`createSandbox.volumes.version`; one of, optional) — 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. - one of: `NodeDriveVersion`, `null` - `public_ports` (`createSandbox.public_ports`; array, optional) — Ports anybody may open at their short preview URL. - min 1; max 65535 - `public_ports_except` (`createSandbox.public_ports_except`; array | null, optional) — 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. - `awake_ports` (`createSandbox.awake_ports`; array | null, optional) — Ports on which a connection upgraded through the preview URL (a WebSocket: a browser's DevTools client on 9222, the viewer of a screen on 6080) keeps the sandbox awake for as long as it is open, and is billed for. While this names a port, the sandbox is idle by those connections and by the requests and calls it is given, and by nothing its guest does: its CPU, its timers, its connections to anywhere and their traffic do not keep it awake, and it is not woken for a timer (what came due meanwhile fires when the next connection wakes it). It goes to sleep `sleep_after_seconds` after the last of them ended, without its guest being asked. Such a connection has TCP's keepalive on its client's side, so that a client that went away without closing it is found out within about a minute. Null or `[]` (the default): idle as any sandbox is. Kept in order, without duplicates. Not for a one-shot run (`POST /v1/run`). A session of Browsers (reports/browsers/README.md) is made with `[9222]`. - `connection_idle_seconds` (`createSandbox.connection_idle_seconds`; integer | null, optional) — A connection on one of `awake_ports` that has carried nothing in either direction for this long is closed by the node (and the sandbox, if nothing else holds it, sleeps `sleep_after_seconds` after that). Null (the default): never for that. Holds for the connections that open after it is set. - min 1; max 86400 - `inbound` (`createSandbox.inbound`; array | null, optional) — 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_seconds` (`createSandbox.sleep_after_seconds`; number | null, optional) — Sleep after this long idle. Null: never by itself. The default is the node's (`--sleep-after-seconds`, 30 unless set). - min 1; max 1000000000; default `30` - `expires_at` (`createSandbox.expires_at`; string | null, optional) — 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_expiry` (`createSandbox.on_expiry`; string | null, optional) — 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`. - one of `"delete"`, `"sleep"`, `"hold"`, `null`; default `"delete"` - `held_asleep` (`createSandbox.held_asleep`; boolean | null, optional) — 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_ms` (`createSandbox.sleep_notice_ms`; integer | null, optional) — How long before the idle rule puts the sandbox to sleep (or pauses it) every program connected to its guest's `/run/sbx/awake` is sent the line `sleep N`, in milliseconds; the sleep comes that long after, unless a hold raised meanwhile puts it off (`sleep_hold_max_ms`). Where nobody is connected, the sleep is not put off. A sleep somebody asks for (`POST /v1/sandboxes/{id}/sleep`, a freeze, a move, the node stopping) is told nothing. 0, null or absent: not told. - min 0; max 60000 - `sleep_hold_max_ms` (`createSandbox.sleep_hold_max_ms`; integer | null, optional) — How long the holds a program in its guest raises (`+` on `/run/sbx/awake`) keep the sandbox up at the most, in milliseconds, counted from the moment it was first found held while nothing else kept it up; then it sleeps whatever holds it (the programs connected are told `sleep N cap` first, where `sleep_notice_ms` asks for a notice), and the count begins again at its next quiet. Held, it runs and is metered as running. 0: holds are not heeded. Null or absent: the node's (`--sleep-hold-max-seconds`, 30 s unless set). - min 0; max 900000 - `suspend_after_ms` (`createSandbox.suspend_after_ms`; integer | null, optional) — How long the pause tier (`pause_tier` of `GET /internal/node`) holds the sandbox paused, once the idle rule has stopped it, before its memory is saved and it sleeps for real, in milliseconds. Paused, it answers in a millisecond or two and is metered for the memory it holds; asleep, for what it keeps on disk. The node's `--pause-max-seconds` (600 unless set) is also the longest it is held paused whatever this says: a paused machine holds the host's memory. The host's memory below the floor, a slot another machine needs and a sleep somebody asks for put it to sleep sooner. Null or absent: the node's. Of no effect where the node has no pause tier. - min 1000; max 86400000 - `wake_daily_at` (`createSandbox.wake_daily_at`; string | null, optional) — A time of day in UTC, `HH:MM`, at which the node wakes the sandbox every day while it sleeps or stands paused, for work of its own that waits for a wake and keeps no time (a database's maintenance, say). The wake is no activity: what runs then is, and once that is done the idle rule puts it to sleep again. Not for a sandbox that is idle by its connections (`awake_ports`). A stateful service's instance (its start command held back for its volumes) is woken besides for the next run of its PostgreSQL server's `pg_cron` jobs, which the node asks its agent for before it rests; while a job runs, or is due within 5 s, the idle rule does not rest it. Null or absent: none. - pattern `^([01][0-9]|2[0-3]):[0-5][0-9]$` - `delete_after_idle_ms` (`createSandbox.delete_after_idle_ms`; integer | null, optional) — Delete the sandbox once it has slept for this long, in milliseconds (`Sandbox.idle_since`); a wake starts the count again at the next sleep. Null or absent: never for that. Less than 1000 is refused (400 `invalid_field`). - format `int64`; min 1000 - `hostname` (`createSandbox.hostname`; string | null, optional) — The name the sandbox's machine has, for good, in place of its id: what `hostname` says in it, from its first boot and after every restart. Lower-case letters, digits and hyphens, in labels between dots; otherwise 400 `invalid_field`. The control plane gives a service's instance the service's name (or the service's `hostname`). Not given: the sandbox's id. - maxLength 63; pattern `^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$` - `stop` (`createSandbox.stop`; object | null, optional) — 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`. - `signal` (`createSandbox.stop.signal`; string | null, optional) — By its name, with `SIG` or without. Null: the image's own (its `STOPSIGNAL`), else SIGTERM. - one of `"SIGTERM"`, `"SIGINT"`, `"SIGQUIT"`, `"SIGHUP"`, `"SIGUSR1"`, `"SIGUSR2"`, `"SIGKILL"`, `"SIGWINCH"`, `"SIGPWR"`, `"SIGSTOP"`, `"TERM"`, `"INT"`, `"QUIT"`, `"HUP"`, `"USR1"`, `"USR2"`, `"KILL"`, `"WINCH"`, `"PWR"`, `"STOP"`, `null` - `grace_ms` (`createSandbox.stop.grace_ms`; integer | null, optional) — Null or not given: 10000. - min 0; max 600000 - `log` (`createSandbox.log`; object | null, optional) — The app's log the sandbox's lines go to, as the lines of the app's instances do (`readAppLog`): what its start command prints, a line for each request through its ports and what the node does to it (made, stopped, deleted). For a sandbox made from the app's version's template (`template`, the key the log knows the version by), of its owner's: the control plane gives it for an app's keyed instance and for a stateful service's. Nothing of the app's group holds for it otherwise: it is no instance the app's requests are given to, and sleeps and is deleted as a sandbox. Without `template`: 400 `invalid_field`. - `app` (`createSandbox.log.app`; string, required) — What the control plane calls the app: the log's name, as `metadata.app` of `setApp` gives it. - minLength 1; maxLength 64 - `version` (`createSandbox.log.version`; string | null, optional) — And the version, which its lines say. - minLength 1; maxLength 64 - `checkpoint` (`createSandbox.checkpoint`; one of, optional) — Checkpoints while the sandbox runs: every `every_seconds` its memory and its disk as they are at one instant go to the node's object store (the node pauses its machine for a few milliseconds for it; what it wrote since the last one is what goes), so that when the node's host is lost the sandbox is taken over elsewhere with its processes, from its newest checkpoint, losing at most what it did since. A checkpoint is begun only once the one before is in the store: a sandbox that writes more than the node's link for them takes falls behind (`checkpoint.behind_seconds`) rather than filling it. Asleep, its sleep's image is what it is taken over from. Null (the default): none. Any sandbox may have it, given when it is made or by a `PATCH` (the control plane also gives it to the keyed instances of an app whose `checkpoint` says so); what the store keeps of its newest checkpoint is billed as a sleeping sandbox's state while it runs (`checkpoint.stored_bytes`). A node that does not copy disks to an object store (`--upload`), or whose memory is not in layers, refuses it (409 `checkpoints_unavailable`, `param` `checkpoint`), and a control plane makes a sandbox with it only on a node that takes checkpoints. Its Drives are pinned with its own disk at the same instant, and a takeover from it brings them back as they were then, with its memory; none is taken while a volume that is not a Drive is attached (such a volume has no copy in the store), or while a read of its guest is held up on a drive of its machine. A checkpoint does not reset the guest's vsock connections (the agent's calls go on), and the first one after a wake from a sleep whose image the store has sends only what the guest wrote since. - one of: `object`, `null` - `region` (`createSandbox.region`; string | null, optional) — 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. - one of `"na"`, `"eu"`, `"ap"`, `null` ## Example request ```json { "start": true, "start_command": "string", "ready": { "tcp": true, "port": 1 }, "egress": { "default": "allow", "allow": [ "string" ], "deny": [ "string" ], "http": [ { "host": "string", "allow": [ { "methods": [ "string" ], "paths": [ "string" ] } ] } ], "inject": [ { "host": "string", "headers": { "property1": "string", "property2": "string" } } ], "deny_ports": [ 1 ] }, "guest_mitigations": true, "tmp": "disk", "runtime": { "ulimits": { "property1": -1, "property2": -1 }, "sysctls": { "property1": "string", "property2": "string" }, "tmpfs": [ { "path": "string", "size_bytes": 1048576, "mode": 4095 } ], "dns": { "servers": [ "string" ], "search": [ "string" ], "options": [ "string" ] }, "shm_size_bytes": 1048576 }, "init": "systemd", "project_network": true, "image": "string", "image_pull_secret": "string", "snapshot": "string", "template": "string", "limits": { "vcpus": 1, "memory_bytes": 134217728 }, "name": "string", "env": { "property1": "string", "property2": "string" }, "secret_env": { "property1": "string", "property2": "string" }, "metadata": { "property1": "string", "property2": "string" }, "volumes": [ { "path": "string", "volume": "string", "read_only": false, "copy": false, "version": { "name": "string", "bytes": 0, "epoch": 1, "number": 1, "token": "string", "refs": "string", "store": "string", "key": "string" } } ], "public_ports": [ 1 ], "public_ports_except": [ 1 ], "awake_ports": [ 1 ], "connection_idle_seconds": 1, "inbound": [ { "protocol": "tcp", "port": 1, "from": [ "string" ] } ], "sleep_after_seconds": 30, "expires_at": "2019-08-24T14:15:22Z", "on_expiry": "delete", "held_asleep": false, "sleep_notice_ms": 60000, "sleep_hold_max_ms": 900000, "suspend_after_ms": 1000, "wake_daily_at": "string", "delete_after_idle_ms": 1000, "hostname": "string", "stop": { "signal": "SIGTERM", "grace_ms": 600000 }, "log": { "app": "string", "version": "string" }, "checkpoint": { "every_seconds": 1 }, "region": "na" } ``` ## Code samples ### cURL ```bash curl --request POST \ --url https://api.glac.ai/v1/sandboxes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data ' { "start": true, "start_command": "string", "ready": { "tcp": true, "port": 1 }, "egress": { "default": "allow", "allow": [ "string" ], "deny": [ "string" ], "http": [ { "host": "string", "allow": [ { "methods": [ "string" ], "paths": [ "string" ] } ] } ], "inject": [ { "host": "string", "headers": { "property1": "string", "property2": "string" } } ], "deny_ports": [ 1 ] }, "guest_mitigations": true, "tmp": "disk", "runtime": { "ulimits": { "property1": -1, "property2": -1 }, "sysctls": { "property1": "string", "property2": "string" }, "tmpfs": [ { "path": "string", "size_bytes": 1048576, "mode": 4095 } ], "dns": { "servers": [ "string" ], "search": [ "string" ], "options": [ "string" ] }, "shm_size_bytes": 1048576 }, "init": "systemd", "project_network": true, "image": "string", "image_pull_secret": "string", "snapshot": "string", "template": "string", "limits": { "vcpus": 1, "memory_bytes": 134217728 }, "name": "string", "env": { "property1": "string", "property2": "string" }, "secret_env": { "property1": "string", "property2": "string" }, "metadata": { "property1": "string", "property2": "string" }, "volumes": [ { "path": "string", "volume": "string", "read_only": false, "copy": false, "version": { "name": "string", "bytes": 0, "epoch": 1, "number": 1, "token": "string", "refs": "string", "store": "string", "key": "string" } } ], "public_ports": [ 1 ], "public_ports_except": [ 1 ], "awake_ports": [ 1 ], "connection_idle_seconds": 1, "inbound": [ { "protocol": "tcp", "port": 1, "from": [ "string" ] } ], "sleep_after_seconds": 30, "expires_at": "2019-08-24T14:15:22Z", "on_expiry": "delete", "held_asleep": false, "sleep_notice_ms": 60000, "sleep_hold_max_ms": 900000, "suspend_after_ms": 1000, "wake_daily_at": "string", "delete_after_idle_ms": 1000, "hostname": "string", "stop": { "signal": "SIGTERM", "grace_ms": 600000 }, "log": { "app": "string", "version": "string" }, "checkpoint": { "every_seconds": 1 }, "region": "na" } ' ``` ### TypeScript ```typescript const url = 'https://api.glac.ai/v1/sandboxes'; const options = { method: 'POST', headers: {'Content-Type': 'application/json', Authorization: 'Bearer '}, body: JSON.stringify({ start: true, start_command: 'string', ready: {tcp: true, port: 1}, egress: { default: 'allow', allow: ['string'], deny: ['string'], http: [{host: 'string', allow: [{methods: ['string'], paths: ['string']}]}], inject: [{host: 'string', headers: {property1: 'string', property2: 'string'}}], deny_ports: [1] }, guest_mitigations: true, tmp: 'disk', runtime: { ulimits: {property1: -1, property2: -1}, sysctls: {property1: 'string', property2: 'string'}, tmpfs: [{path: 'string', size_bytes: 1048576, mode: 4095}], dns: {servers: ['string'], search: ['string'], options: ['string']}, shm_size_bytes: 1048576 }, init: 'systemd', project_network: true, image: 'string', image_pull_secret: 'string', snapshot: 'string', template: 'string', limits: {vcpus: 1, memory_bytes: 134217728}, name: 'string', env: {property1: 'string', property2: 'string'}, secret_env: {property1: 'string', property2: 'string'}, metadata: {property1: 'string', property2: 'string'}, volumes: [ { path: 'string', volume: 'string', read_only: false, copy: false, version: { name: 'string', bytes: 0, epoch: 1, number: 1, token: 'string', refs: 'string', store: 'string', key: 'string' } } ], public_ports: [1], public_ports_except: [1], awake_ports: [1], connection_idle_seconds: 1, inbound: [{protocol: 'tcp', port: 1, from: ['string']}], sleep_after_seconds: 30, expires_at: '2019-08-24T14:15:22Z', on_expiry: 'delete', held_asleep: false, sleep_notice_ms: 60000, sleep_hold_max_ms: 900000, suspend_after_ms: 1000, wake_daily_at: 'string', delete_after_idle_ms: 1000, hostname: 'string', stop: {signal: 'SIGTERM', grace_ms: 600000}, log: {app: 'string', version: 'string'}, checkpoint: {every_seconds: 1}, region: 'na' }) }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err)); ``` ### Python ```python import requests url = "https://api.glac.ai/v1/sandboxes" payload = { "start": True, "start_command": "string", "ready": { "tcp": True, "port": 1 }, "egress": { "default": "allow", "allow": ["string"], "deny": ["string"], "http": [ { "host": "string", "allow": [ { "methods": ["string"], "paths": ["string"] } ] } ], "inject": [ { "host": "string", "headers": { "property1": "string", "property2": "string" } } ], "deny_ports": [1] }, "guest_mitigations": True, "tmp": "disk", "runtime": { "ulimits": { "property1": -1, "property2": -1 }, "sysctls": { "property1": "string", "property2": "string" }, "tmpfs": [ { "path": "string", "size_bytes": 1048576, "mode": 4095 } ], "dns": { "servers": ["string"], "search": ["string"], "options": ["string"] }, "shm_size_bytes": 1048576 }, "init": "systemd", "project_network": True, "image": "string", "image_pull_secret": "string", "snapshot": "string", "template": "string", "limits": { "vcpus": 1, "memory_bytes": 134217728 }, "name": "string", "env": { "property1": "string", "property2": "string" }, "secret_env": { "property1": "string", "property2": "string" }, "metadata": { "property1": "string", "property2": "string" }, "volumes": [ { "path": "string", "volume": "string", "read_only": False, "copy": False, "version": { "name": "string", "bytes": 0, "epoch": 1, "number": 1, "token": "string", "refs": "string", "store": "string", "key": "string" } } ], "public_ports": [1], "public_ports_except": [1], "awake_ports": [1], "connection_idle_seconds": 1, "inbound": [ { "protocol": "tcp", "port": 1, "from": ["string"] } ], "sleep_after_seconds": 30, "expires_at": "2019-08-24T14:15:22Z", "on_expiry": "delete", "held_asleep": False, "sleep_notice_ms": 60000, "sleep_hold_max_ms": 900000, "suspend_after_ms": 1000, "wake_daily_at": "string", "delete_after_idle_ms": 1000, "hostname": "string", "stop": { "signal": "SIGTERM", "grace_ms": 600000 }, "log": { "app": "string", "version": "string" }, "checkpoint": { "every_seconds": 1 }, "region": "na" } headers = { "Content-Type": "application/json", "Authorization": "Bearer " } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## Responses ### 201 The sandbox. #### Example ```json { "id": "string", "awake_ports": [ 1 ], "connection_idle_seconds": 1, "awake_connections": 0, "start_command": { "status": "string", "restarts": 0, "last_exit": { "status": 0, "signal": 0, "at": "2019-08-24T14:15:22Z" }, "restarting_at": "2019-08-24T14:15:22Z" }, "devtools": { "port": 1, "path": "string" }, "proxy": { "url": "string", "username": "string" }, "image_digest": "string", "app_id": "string", "version_id": "string", "key": "string", "app": "string", "ipv6": "string", "inbound": [ { "protocol": "tcp", "port": 1, "from": [ "string" ] } ], "checkpoint": { "every_seconds": 1, "last_at": "2019-08-24T14:15:22Z", "behind_seconds": 0, "bytes_per_second": 0, "stored_bytes": 0, "error": "string" }, "secret_env": [ "string" ], "object": "sandbox", "name": "string", "status": "string", "sleep_tier": "string", "failure": "string", "failure_code": "string", "image": "string", "snapshot": "string", "env": { "property1": "string", "property2": "string" }, "metadata": { "property1": "string", "property2": "string" }, "volumes": [ { "path": "string", "volume": "string", "name": "string", "read_only": true, "shared": true, "kind": "string", "view_of": { "drive": "string", "version": { "name": "string", "bytes": 0, "epoch": 1, "number": 1, "token": "string", "refs": "string", "store": "string", "key": "string" } } } ], "public_ports": [ 1 ], "public_ports_except": [ 1 ], "egress": { "default": "allow", "allow": [ "string" ], "deny": [ "string" ], "http": [ { "host": "string", "allow": [ { "methods": [ "string" ], "paths": [ "string" ] } ] } ], "inject": [ { "host": "string", "headers": { "property1": "string", "property2": "string" } } ], "deny_ports": [ 1 ] }, "sleep_after_seconds": 0, "expires_at": "2019-08-24T14:15:22Z", "on_expiry": "delete", "held_asleep": true, "sleep_notice_ms": 0, "sleep_hold_max_ms": 0, "suspend_after_ms": 1000, "wake_daily_at": "string", "delete_after_idle_ms": 1000, "idle_since": "2019-08-24T14:15:22Z", "limits": { "vcpus": 0, "memory_bytes": 0, "disk_bytes": 0 }, "guest_mitigations": true, "tmp": "disk", "init": "systemd", "created_at": "2019-08-24T14:15:22Z", "booted_at": "2019-08-24T14:15:22Z", "last_active_at": "2019-08-24T14:15:22Z", "awake_because": "string", "usage": { "proxy_sent_bytes": 0, "proxy_received_bytes": 0, "awake_seconds": 0, "egress_refused_requests": 0, "cpu_seconds": 0, "memory_gib_seconds": 0, "memory_bytes": 0, "disk_bytes": 0, "egress_bytes": 0 }, "host_failure": { "at": "2019-08-24T14:15:22Z", "cause": "string", "memory": "string", "disk": "string", "disk_as_of": "2019-08-24T14:15:22Z", "detail": "string" }, "project_address": "string", "region": "string", "usable_at": "2019-08-24T14:15:22Z", "hydrated_at": "2019-08-24T14:15:22Z", "hydrated_bytes": 0, "total_bytes": 0, "disk_writes": { "today_bytes": 0, "checkpoint_copy_bytes": 0, "full_speed_until_bytes": 0, "limited": true, "limited_until": "2019-08-24T14:15:22Z" }, "url_secret": "string", "url_pattern": "string" } ``` - `id` (`createSandbox.response.201.id`; string, required) — `sbx-` and 16 characters; valid as a DNS label. - pattern `^sbx-[0-9a-hjkmnp-tv-z]{16}$` - `awake_ports` (`createSandbox.response.201.awake_ports`; array, required) — 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. - min 1; max 65535 - `connection_idle_seconds` (`createSandbox.response.201.connection_idle_seconds`; integer | null, required) — How long a connection on one of `awake_ports` may carry nothing before the node closes it (`SandboxCreate`); null: never for that. - min 1 - `awake_connections` (`createSandbox.response.201.awake_connections`; integer, required) — 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. - min 0 - `start_command` (`createSandbox.response.201.start_command`; one of, required) — 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. - one of: `SandboxStartCommand`, `null` - `devtools` (`createSandbox.response.201.devtools`; object | null, required) — 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. - `port` (`createSandbox.response.201.devtools.port`; integer, required) - min 1; max 65535 - `path` (`createSandbox.response.201.devtools.path`; string, required) — `/devtools/browser/`. - pattern `^/devtools/browser/[A-Za-z0-9-]{1,64}$` - `proxy` (`createSandbox.response.201.proxy`; one of, required) — Its own proxy (`SandboxCreate`'s `proxy`): its address and the user name it is asked with, never its password. Null where it has none. - one of: `SandboxProxy`, `null` - `image_digest` (`createSandbox.response.201.image_digest`; string | null, required) — 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,}$` - `app` (`createSandbox.response.201.app`; string | null, required) — 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. - `ipv6` (`createSandbox.response.201.ipv6`; string | null, required) — 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). - `inbound` (`createSandbox.response.201.inbound`; array, required) — 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. - `protocol` (`createSandbox.response.201.inbound.protocol`; string, required) - one of `"tcp"`, `"udp"` - `port` (`createSandbox.response.201.inbound.port`; integer, required) - min 1; max 65535 - `from` (`createSandbox.response.201.inbound.from`; array, required) — 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. - `checkpoint` (`createSandbox.response.201.checkpoint`; one of, required) — Its checkpoints while it runs (`SandboxCreate`'s `checkpoint`), and how they go; null where it has none. - one of: `CheckpointStatus`, `null` - `secret_env` (`createSandbox.response.201.secret_env`; array, required) — The names of the variables of `secret_env` it was made with, in order; never a value. Empty for one made with none. - `object` (`createSandbox.response.201.object`; string, required) - `name` (`createSandbox.response.201.name`; one of, required) — The name the caller gave it, or null. - one of: `Name`, `null` - `status` (`createSandbox.response.201.status`; string, required) — 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_tier` (`createSandbox.response.201.sleep_tier`; one of, required) — 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. - one of: `string`, `null` - `failure` (`createSandbox.response.201.failure`; string | null, required) — 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_code` (`createSandbox.response.201.failure_code`; one of, required) — 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. - one of: `string`, `null` - `image` (`createSandbox.response.201.image`; string | null, required) — The OCI image reference the sandbox goes back to. Null only on a node whose base template was built from a disk file. - `snapshot` (`createSandbox.response.201.snapshot`; string | null, required) — 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}$` - `metadata` (`createSandbox.response.201.metadata`; map, required) — 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). - `volumes` (`createSandbox.response.201.volumes`; array, required) - `path` (`createSandbox.response.201.volumes.path`; string, required) — Where it is mounted. - `volume` (`createSandbox.response.201.volumes.volume`; string, required) — The volume's id (never its name). - pattern `^vol-[0-9a-hjkmnp-tv-z]{16}$` - `name` (`createSandbox.response.201.volumes.name`; string | null, required) — The volume's name, if it has one. - `read_only` (`createSandbox.response.201.volumes.read_only`; boolean, required) - `shared` (`createSandbox.response.201.volumes.shared`; boolean, required) — True for a shared volume (served by the node over NFS), false for one that is this sandbox's alone (a block device). - `kind` (`createSandbox.response.201.volumes.kind`; string | null, optional) — 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_of` (`createSandbox.response.201.volumes.view_of`; object | null, optional) — 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. - `drive` (`createSandbox.response.201.volumes.view_of.drive`; string, required) - pattern `^vol-[0-9a-hjkmnp-tv-z]{16}$` - `version` (`createSandbox.response.201.volumes.view_of.version`; object, required) — 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. - `name` (`createSandbox.response.201.volumes.view_of.version.name`; string, required) — 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]+$` - `bytes` (`createSandbox.response.201.volumes.view_of.version.bytes`; integer, required) - format `int64`; min 0 - `epoch` (`createSandbox.response.201.volumes.view_of.version.epoch`; integer, required) - format `int64`; min 1 - `number` (`createSandbox.response.201.volumes.view_of.version.number`; integer, required) - format `int64`; min 1 - `token` (`createSandbox.response.201.volumes.view_of.version.token`; string, required) - pattern `^[0-9a-f]+$` - `refs` (`createSandbox.response.201.volumes.view_of.version.refs`; string, required) — Its list of references, in the store: what the control plane's collector keeps for it. - `store` (`createSandbox.response.201.volumes.view_of.version.store`; string, required) — The identity of the store its root, pages and frames are in. - `key` (`createSandbox.response.201.volumes.view_of.version.key`; string, required) — The number of the key it is sealed with (empty where a version from before keys were numbered). - `public_ports` (`createSandbox.response.201.public_ports`; array, required) — Ports whose preview URL needs no signature and no token. Duplicates are kept as given. - min 1; max 65535 - `public_ports_except` (`createSandbox.response.201.public_ports_except`; array | null, required) — 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. - `egress` (`createSandbox.response.201.egress`; object, required) — 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. - `default` (`createSandbox.response.201.egress.default`; string, required) — What happens to what neither list speaks of. - one of `"allow"`, `"deny"` - `allow` (`createSandbox.response.201.egress.allow`; array, required) — Reached under `default: deny`. Empty under `default: allow`. - maxLength 300 - `deny` (`createSandbox.response.201.egress.deny`; array, required) — Never reached, whatever `allow` says. - maxLength 300 - `http` (`createSandbox.response.201.egress.http`; array, required) — 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. - `host` (`createSandbox.response.201.egress.http.host`; string, required) — A host name, or `*.` and a name. Not an address. - maxLength 300 - `allow` (`createSandbox.response.201.egress.http.allow`; array, required) — The requests that pass. A host that is to get none goes in `deny`. - `methods` (`createSandbox.response.201.egress.http.allow.methods`; array | null, optional) — 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. - `paths` (`createSandbox.response.201.egress.http.allow.paths`; array | null, optional) — 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`. - `inject` (`createSandbox.response.201.egress.inject`; array, required) — Headers the node adds to the sandbox's HTTPS requests to a host. - `host` (`createSandbox.response.201.egress.inject.host`; string, required) — A host name, or `*.` and a name. Not an address. - maxLength 300 - `headers` (`createSandbox.response.201.egress.inject.headers`; map, required) — 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_ports` (`createSandbox.response.201.egress.deny_ports`; array, optional) — 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. - min 1; max 65535 - `sleep_after_seconds` (`createSandbox.response.201.sleep_after_seconds`; number | null, required) — 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. - min 0 - `expires_at` (`createSandbox.response.201.expires_at`; string | null, required) — When the sandbox deletes itself (or what `on_expiry` says). Null: never. - format `date-time` - `on_expiry` (`createSandbox.response.201.on_expiry`; string, required) — 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. - one of `"delete"`, `"sleep"`, `"hold"` - `held_asleep` (`createSandbox.response.201.held_asleep`; boolean, required) — 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_ms` (`createSandbox.response.201.sleep_notice_ms`; integer | null, required) — 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_ms` (`createSandbox.response.201.sleep_hold_max_ms`; integer, required) — 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. - min 0 - `suspend_after_ms` (`createSandbox.response.201.suspend_after_ms`; integer, required) — 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. - min 1000 - `wake_daily_at` (`createSandbox.response.201.wake_daily_at`; string | null, required) — 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_ms` (`createSandbox.response.201.delete_after_idle_ms`; integer | null, required) — 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`; min 1000 - `idle_since` (`createSandbox.response.201.idle_since`; string | null, required) — 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` - `limits` (`createSandbox.response.201.limits`; object, required) — 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. - `vcpus` (`createSandbox.response.201.limits.vcpus`; integer, required) — Virtual CPUs. - min 0 - `memory_bytes` (`createSandbox.response.201.limits.memory_bytes`; integer, required) — Memory the machine has. - format `int64`; min 0 - `disk_bytes` (`createSandbox.response.201.limits.disk_bytes`; integer, required) — The size of the root disk. 0 while a sandbox is `starting` and has no disk yet. - format `int64`; min 0 - `guest_mitigations` (`createSandbox.response.201.guest_mitigations`; boolean, required) — Whether the guest kernel keeps its mitigations against speculative execution (`guest_mitigations` at creation). - `tmp` (`createSandbox.response.201.tmp`; string, required) — 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. - one of `"disk"`, `"memory"` - `created_at` (`createSandbox.response.201.created_at`; string, required) - format `date-time` - `booted_at` (`createSandbox.response.201.booted_at`; string | null, required) — 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_at` (`createSandbox.response.201.last_active_at`; string | null, required) — 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_because` (`createSandbox.response.201.awake_because`; string | null, required) — 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`). - `usage` (`createSandbox.response.201.usage`; object, required) — What the sandbox has used and uses. - `proxy_sent_bytes` (`createSandbox.response.201.usage.proxy_sent_bytes`; integer, required) — 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`; min 0 - `proxy_received_bytes` (`createSandbox.response.201.usage.proxy_received_bytes`; integer, required) — 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`; min 0 - `awake_seconds` (`createSandbox.response.201.usage.awake_seconds`; number, required) — 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`). - min 0 - `egress_refused_requests` (`createSandbox.response.201.usage.egress_refused_requests`; integer, required) — 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`; min 0 - `cpu_seconds` (`createSandbox.response.201.usage.cpu_seconds`; number, required) — 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. - min 0 - `memory_gib_seconds` (`createSandbox.response.201.usage.memory_gib_seconds`; number, required) — 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. - min 0 - `memory_bytes` (`createSandbox.response.201.usage.memory_bytes`; integer, required) — 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`; min 0 - `disk_bytes` (`createSandbox.response.201.usage.disk_bytes`; integer, required) — Bytes the root disk takes on the node now. - format `int64`; min 0 - `egress_bytes` (`createSandbox.response.201.usage.egress_bytes`; integer, required) — 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`; min 0 - `host_failure` (`createSandbox.response.201.host_failure`; one of, required) — 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. - one of: `SandboxHostFailure`, `null` - `project_address` (`createSandbox.response.201.project_address`; string | null, required) — 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}$` - `region` (`createSandbox.response.201.region`; one of, required) — 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. - one of: `string`, `null` - `usable_at` (`createSandbox.response.201.usable_at`; string | null, required) — 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_at` (`createSandbox.response.201.hydrated_at`; string | null, required) — 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_bytes` (`createSandbox.response.201.hydrated_bytes`; integer | null, required) — 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`; min 0 - `total_bytes` (`createSandbox.response.201.total_bytes`; integer | null, required) — 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`; min 0 - `disk_writes` (`createSandbox.response.201.disk_writes`; one of, required) — 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. - one of: `SandboxDiskWrites`, `null` - `app_id` (`createSandbox.response.201.app_id`; string, optional) — 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_id` (`createSandbox.response.201.version_id`; string, optional) — 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. - `key` (`createSandbox.response.201.key`; string, optional) — With `app_id`: what it is found by among the app's instances, its name, or its id where it has none. - `env` (`createSandbox.response.201.env`; map, optional) — 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. - `init` (`createSandbox.response.201.init`; one of, optional) — 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/). - one of: `string`, `null` - `url_secret` (`createSandbox.response.201.url_secret`; string, optional) — Signs this sandbox's preview links. Absent (not null) when the caller is a sandbox token. - pattern `^[0-9a-f]{32}$` - `url_pattern` (`createSandbox.response.201.url_pattern`; string | null, optional) — 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. ### 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 `/`; `invalid_idempotency_key`: `Idempotency-Key` is empty or over 255 characters. #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.400.error`; object, required) - `type` (`createSandbox.response.400.error.type`; string, required) — 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. - `code` (`createSandbox.response.400.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.400.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.400.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.400.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.400.error.request_id`; string, required) — 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_url` (`createSandbox.response.400.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.400.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.400.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.400.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.400.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.400.exec_id`; string, optional) — 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_ms` (`createSandbox.response.400.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.400.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.400.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.400.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.400.image`; string, optional) — 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}$` - `build` (`createSandbox.response.400.build`; string, optional) — 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`. #### Example ```json { "move_id": "string", "upgrade_id": "string", "move": { "object": "move", "id": "string", "sandbox_id": "string", "project_id": "string", "from": { "id": "string", "name": "string" }, "to": { "id": "string", "name": "string" }, "epoch": 1, "step": "string", "why": "string", "wake": true, "from_store": true, "release": {}, "takeover": {}, "error": { "code": "string", "message": "string", "status": 0, "takeover_refused": { "code": "string", "message": "string", "status": 0 }, "image": "string", "holder": "string", "holder_says": "has" }, "attempts": 0, "next_attempt_at": "2019-08-24T14:15:22Z", "batch": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "ended_at": "2019-08-24T14:15:22Z" }, "lease_until": "2019-08-24T14:15:22Z", "active": { "name": "string", "url": "string", "term": 1 }, "allowed_hosts": [ "string" ], "problems": [ { "at": "string", "message": "string" } ], "report": { "object": "compose_import", "name": "string", "dry_run": true, "strict": true, "profiles": [ "string" ], "treatments": { "done": 0, "adapted": 0, "ignored": 0, "refused": 0 }, "items": [ { "at": "string", "treatment": "done", "why": "string", "change": "string" } ], "services": [ { "name": "string", "app_id": "string", "status": "created", "kind": "service", "stateful": true, "version": true, "items": [ { "at": "string", "treatment": "done", "why": "string", "change": "string" } ], "app": { "image": "string", "image_pull_secret": "string", "start_command": "string", "start_args": [ "string" ], "port": 0, "ready": { "http": "string" }, "env": { "property1": "string", "property2": "string" }, "secrets": { "property1": "string", "property2": "string" }, "size": { "vcpus": 1, "memory_bytes": 134217728 }, "volumes": [ { "volume": "string", "path": "string", "read_only": true, "nocopy": true } ], "drives": [ { "drive": "string", "path": "string", "mode": "string" } ], "key_drives": [ { "name": "string", "path": "string", "size_bytes": 0, "nocopy": true } ], "kind": "string", "files": [ { "path": "string", "content": "string", "secret": "string", "mode": 0, "uid": 0, "gid": 0 } ], "user": "string", "working_dir": "string", "stop": { "signal": "string", "grace_ms": 0 }, "hostname": "string", "runtime": { "ulimits": { "property1": {}, "property2": {} }, "sysctls": { "property1": "string", "property2": "string" }, "tmpfs": [ {} ], "dns": { "servers": [ null ], "search": [ null ], "options": [ null ] }, "shm_size_bytes": 0 }, "regions": [ "string" ], "scale": { "min_instances": 0, "max_instances": 1, "concurrency": 1, "sleep_after_ms": 600000, "sleep_notice_ms": 60000, "sleep_hold_max_ms": 900000, "suspend_after_ms": 1000, "wake_daily_at": "string", "delete_after_ms": 1000 }, "keys": { "from": { "header": "string" }, "upgrade_on_deploy": true, "delete_after_idle_ms": 1000 }, "egress": { "default": "allow", "allow": [ "string" ], "deny": [ "string" ], "http": [ { "allow": [] } ], "inject": [ { "headers": {} } ], "deny_ports": [ 1 ] }, "metadata": { "property1": "string", "property2": "string" }, "logs": { "output": true, "keep": true, "requests": { "sample_rate": 1, "keep_errors": true } }, "traces": { "sample_rate": 1, "trust_incoming": true }, "public": true, "depends_on": [ { "service": "string", "condition": "string" } ], "network": { "aliases": [ "string" ], "endpoint_mode": "string" } } } ], "volumes": [ { "model": "string", "name": "string", "id": "string", "shared": true, "status": "to_make", "used_by": [ "string" ] } ], "secrets": [ { "model": "string", "name": "string", "there": true, "used_by": [ "string" ] } ], "left_out": [ { "name": "string", "profiles": [ "string" ] } ], "absent": [ "string" ], "deploy": "string" }, "accounts": [ { "id": "string", "name": "string" } ], "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" } } ``` - `error` (`createSandbox.response.401.error`; object, required) - `type` (`createSandbox.response.401.error.type`; string, required) - `code` (`createSandbox.response.401.error.code`; string, required) - `message` (`createSandbox.response.401.error.message`; string, required) - `param` (`createSandbox.response.401.error.param`; string | null, required) - `retryable` (`createSandbox.response.401.error.retryable`; boolean, required) - `request_id` (`createSandbox.response.401.error.request_id`; string, required) - `docs_url` (`createSandbox.response.401.error.docs_url`; string | null, required) - `move_id` (`createSandbox.response.401.move_id`; string, optional) — With `already_moving`: the move of the sandbox that is under way. - `upgrade_id` (`createSandbox.response.401.upgrade_id`; string, optional) — 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}$` - `move` (`createSandbox.response.401.move`; object, optional) — With `move_over`, `move_going_back` and `move_taken_over` (`POST /internal/moves/{id}/cancel`): the move, as it stands. - `object` (`createSandbox.response.401.move.object`; string, required) - `id` (`createSandbox.response.401.move.id`; string, required) - pattern `^mov-[0-9a-hjkmnp-tv-z]{16}$` - `sandbox_id` (`createSandbox.response.401.move.sandbox_id`; string, required) - `project_id` (`createSandbox.response.401.move.project_id`; string, required) - `from` (`createSandbox.response.401.move.from`; object, required) - `id` (`createSandbox.response.401.move.from.id`; string, required) - `name` (`createSandbox.response.401.move.from.name`; string | null, required) — Its name; null for a node that is off the books since. - `to` (`createSandbox.response.401.move.to`; object, required) - `id` (`createSandbox.response.401.move.to.id`; string, required) - `name` (`createSandbox.response.401.move.to.name`; string | null, required) — Its name; null for a node that is off the books since. - `epoch` (`createSandbox.response.401.move.epoch`; integer, required) — 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. - min 1 - `step` (`createSandbox.response.401.move.step`; string, required) — 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). - `why` (`createSandbox.response.401.move.why`; string, required) — What made it: the operator's move, an evacuation, a recovery. - `wake` (`createSandbox.response.401.move.wake`; boolean, required) — Whether the new node wakes it: as the call said, or as it was (it ran) when the move began. - `from_store` (`createSandbox.response.401.move.from_store`; boolean, required) — The new node takes it from the object store alone. - `release` (`createSandbox.response.401.move.release`; object | null, required) — What the old node's release answered (sandboxd/openapi/openapi.json, `releaseSandbox`), without the release's key; null before it answered. - `takeover` (`createSandbox.response.401.move.takeover`; object | null, required) — 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. - `error` (`createSandbox.response.401.move.error`; one of, required) — 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. - one of: `object`, `null` - `attempts` (`createSandbox.response.401.move.attempts`; integer, required) — How many times the step it is at was asked without an answer that settles it. - min 0 - `next_attempt_at` (`createSandbox.response.401.move.next_attempt_at`; string | null, required) — When that step is asked again; null where it is not waiting. - format `date-time` - `batch` (`createSandbox.response.401.move.batch`; string | null, required) — The evacuation (`evc-…`) or recovery (`rcv-…`) it is of. - `created_at` (`createSandbox.response.401.move.created_at`; string, required) - format `date-time` - `updated_at` (`createSandbox.response.401.move.updated_at`; string, required) - format `date-time` - `ended_at` (`createSandbox.response.401.move.ended_at`; string | null, required) - format `date-time` - `lease_until` (`createSandbox.response.401.lease_until`; string, optional) — 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` - `active` (`createSandbox.response.401.active`; object | null, optional) — With `standby`: the active copy, as the standby last read the lease; null while no copy holds it. - `name` (`createSandbox.response.401.active.name`; string, required) - `url` (`createSandbox.response.401.active.url`; string, required) - `term` (`createSandbox.response.401.active.term`; integer, required) - min 1 - `allowed_hosts` (`createSandbox.response.401.allowed_hosts`; array | null, optional) — 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`). - `problems` (`createSandbox.response.401.problems`; array, optional) — With `invalid_definition`: every problem of the definition, each where it is and what it is. - `at` (`createSandbox.response.401.problems.at`; string, required) — Where in the definition, a dotted path (`services.web.port`); empty for the whole of it. - `message` (`createSandbox.response.401.problems.message`; string, required) - `report` (`createSandbox.response.401.report`; object, optional) — With `compose_refused`: the import's report, which says what is refused, why, and what to change. - `object` (`createSandbox.response.401.report.object`; string, required) - one of `"compose_import"` - `name` (`createSandbox.response.401.report.name`; string | null, required) — The model's `name`: each service's label `compose.project`. Null: it has none. - `dry_run` (`createSandbox.response.401.report.dry_run`; boolean, required) - `strict` (`createSandbox.response.401.report.strict`; boolean, required) - `profiles` (`createSandbox.response.401.report.profiles`; array, required) - `treatments` (`createSandbox.response.401.report.treatments`; object, required) — How many items of the report have each treatment. - `done` (`createSandbox.response.401.report.treatments.done`; integer, required) - min 0 - `adapted` (`createSandbox.response.401.report.treatments.adapted`; integer, required) - min 0 - `ignored` (`createSandbox.response.401.report.treatments.ignored`; integer, required) - min 0 - `refused` (`createSandbox.response.401.report.treatments.refused`; integer, required) - min 0 - `items` (`createSandbox.response.401.report.items`; array, required) — The model's top-level elements: `name`, each volume, network, config and secret, extensions. - `at` (`createSandbox.response.401.report.items.at`; string, required) — 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`). - `treatment` (`createSandbox.response.401.report.items.treatment`; string, required) — `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. - one of `"done"`, `"adapted"`, `"ignored"`, `"refused"` - `why` (`createSandbox.response.401.report.items.why`; string, required) - `change` (`createSandbox.response.401.report.items.change`; string | null, required) — Of one that is refused: what to change. Null otherwise. - `services` (`createSandbox.response.401.report.services`; array, required) — The services the import takes, in the model's order. - `name` (`createSandbox.response.401.report.services.name`; string, required) — The service's name, which is its app's. - `app_id` (`createSandbox.response.401.report.services.app_id`; string | null, required) — Its app. Null: a dry run of a service the project does not have. - pattern `^app-` - `status` (`createSandbox.response.401.report.services.status`; string, required) — What the import does (or, in a dry run, would do) to its app: makes it, writes what changed, or nothing. - one of `"created"`, `"changed"`, `"unchanged"` - `kind` (`createSandbox.response.401.report.services.kind`; string, required) — `job`: a service of the model waits for it to complete, and it runs to its end in each deploy that needs it. - one of `"service"`, `"job"` - `stateful` (`createSandbox.response.401.report.services.stateful`; boolean, required) — It mounts a volume of its own: one instance, which has the volume. - `version` (`createSandbox.response.401.report.services.version`; boolean, required) — 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. - `items` (`createSandbox.response.401.report.services.items`; array, required) - `at` (`createSandbox.response.401.report.services.items.at`; string, required) — 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`). - `treatment` (`createSandbox.response.401.report.services.items.treatment`; string, required) — `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. - one of `"done"`, `"adapted"`, `"ignored"`, `"refused"` - `why` (`createSandbox.response.401.report.services.items.why`; string, required) - `change` (`createSandbox.response.401.report.services.items.change`; string | null, required) — Of one that is refused: what to change. Null otherwise. - `app` (`createSandbox.response.401.report.services.app`; object, required) — The fields of the service's app as the import writes them: what its versions are made of, and what holds at once. - `image` (`createSandbox.response.401.report.services.app.image`; string | null, required) — 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_secret` (`createSandbox.response.401.report.services.app.image_pull_secret`; string | null, required) — The name of the secret that holds the credentials of the image's registry. No answer has its value. `null`: none. - `start_command` (`createSandbox.response.401.report.services.app.start_command`; any of, required) - any of: `StartCommand`, `null` - `start_args` (`createSandbox.response.401.report.services.app.start_args`; any of, required) — What follows the image's ENTRYPOINT in the place of its CMD. `null`: the image's CMD, or the whole of `start_command`. - any of: `array`, `null` - `port` (`createSandbox.response.401.report.services.app.port`; integer | null, required) - `ready` (`createSandbox.response.401.report.services.app.ready`; object, required) — 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`). - `http` (`createSandbox.response.401.report.services.app.ready.http`; string, optional) — A path, beginning with `/`: a `GET` of it on the app's port is answered with a status from 200 to 399. - `tcp` (`createSandbox.response.401.report.services.app.ready.tcp`; boolean, optional) — The app's port takes a connection. - one of `true` - `command` (`createSandbox.response.401.report.services.app.ready.command`; one of, optional) — 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. - one of: `string`, `array` - `env` (`createSandbox.response.401.report.services.app.env`; map, required) - `secrets` (`createSandbox.response.401.report.services.app.secrets`; map, required) — Names of secrets. No answer has a value. - `size` (`createSandbox.response.401.report.services.app.size`; object, required) — What one instance may use at most. It is billed by what it uses. - `vcpus` (`createSandbox.response.401.report.services.app.size.vcpus`; integer, required) - min 1 - `memory_bytes` (`createSandbox.response.401.report.services.app.size.memory_bytes`; integer, required) — 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`). - min 134217728 - `volumes` (`createSandbox.response.401.report.services.app.volumes`; array, required) - `volume` (`createSandbox.response.401.report.services.app.volumes.volume`; string, required) - `path` (`createSandbox.response.401.report.services.app.volumes.path`; string, required) - `read_only` (`createSandbox.response.401.report.services.app.volumes.read_only`; boolean, required) - `nocopy` (`createSandbox.response.401.report.services.app.volumes.nocopy`; unknown, optional) — There only where it was given as `true`. - `kind` (`createSandbox.response.401.report.services.app.kind`; string, required) - `files` (`createSandbox.response.401.report.services.app.files`; array, required) - `path` (`createSandbox.response.401.report.services.app.files.path`; string, required) - `mode` (`createSandbox.response.401.report.services.app.files.mode`; integer, required) - `uid` (`createSandbox.response.401.report.services.app.files.uid`; integer, required) - `gid` (`createSandbox.response.401.report.services.app.files.gid`; integer, required) - `content` (`createSandbox.response.401.report.services.app.files.content`; string, optional) - `secret` (`createSandbox.response.401.report.services.app.files.secret`; string, optional) - `user` (`createSandbox.response.401.report.services.app.user`; string | null, required) - `working_dir` (`createSandbox.response.401.report.services.app.working_dir`; string | null, required) - `stop` (`createSandbox.response.401.report.services.app.stop`; any of, required) - any of: `ServiceStop`, `null` - `hostname` (`createSandbox.response.401.report.services.app.hostname`; string | null, required) - `regions` (`createSandbox.response.401.report.services.app.regions`; array, required) — In the order na, eu, ap. - `scale` (`createSandbox.response.401.report.services.app.scale`; object, required) - `min_instances` (`createSandbox.response.401.report.services.app.scale.min_instances`; integer, required) — 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`. - min 0 - `max_instances` (`createSandbox.response.401.report.services.app.scale.max_instances`; integer | null, required) — 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 the free plan, 50 on `p20`, 200 on `p100`, 500 on `p300`, 1,000 on `p1000`, 2,000 on `p2000`): 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, 10, 20, 50, 100 and 200), 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. - min 1 - `concurrency` (`createSandbox.response.401.report.services.app.scale.concurrency`; integer | null, required) — 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. - min 1; max 1000 - `sleep_after_ms` (`createSandbox.response.401.report.services.app.scale.sleep_after_ms`; integer, required) — After how long without a request an instance stops. 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. - min 0; max 600000 - `sleep_notice_ms` (`createSandbox.response.401.report.services.app.scale.sleep_notice_ms`; integer | null, required) — 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). - min 0; max 60000 - `sleep_hold_max_ms` (`createSandbox.response.401.report.services.app.scale.sleep_hold_max_ms`; integer, required) — 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). - min 0; max 900000 - `delete_after_ms` (`createSandbox.response.401.report.services.app.scale.delete_after_ms`; integer | null, required) — 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. - min 1000; max 3600000 - `suspend_after_ms` (`createSandbox.response.401.report.services.app.scale.suspend_after_ms`; integer | null, optional) — 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. - min 1000; max 86400000 - `wake_daily_at` (`createSandbox.response.401.report.services.app.scale.wake_daily_at`; string | null, optional) — 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]$` - `keys` (`createSandbox.response.401.report.services.app.keys`; any of, required) - any of: `object`, `null` - `egress` (`createSandbox.response.401.report.services.app.egress`; object | null, required) — 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). - `default` (`createSandbox.response.401.report.services.app.egress.default`; string | null, optional) - one of `"allow"`, `"deny"`, `null` - `allow` (`createSandbox.response.401.report.services.app.egress.allow`; array | null, optional) - `deny` (`createSandbox.response.401.report.services.app.egress.deny`; array | null, optional) - `http` (`createSandbox.response.401.report.services.app.egress.http`; array | null, optional) - `inject` (`createSandbox.response.401.report.services.app.egress.inject`; array | null, optional) - `deny_ports` (`createSandbox.response.401.report.services.app.egress.deny_ports`; array | null, optional) — 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. - `metadata` (`createSandbox.response.401.report.services.app.metadata`; map, required) - `logs` (`createSandbox.response.401.report.services.app.logs`; object, required) — What the app's log has, each part as it was given or at its default (`AppLogSettings`). - `output` (`createSandbox.response.401.report.services.app.logs.output`; boolean, required) - `keep` (`createSandbox.response.401.report.services.app.logs.keep`; boolean, required) - `requests` (`createSandbox.response.401.report.services.app.logs.requests`; object, required) - `sample_rate` (`createSandbox.response.401.report.services.app.logs.requests.sample_rate`; number, required) - min 0; max 1 - `keep_errors` (`createSandbox.response.401.report.services.app.logs.requests.keep_errors`; boolean, required) - `public` (`createSandbox.response.401.report.services.app.public`; boolean, required) — Whether it answers at its default domain (`url`). - `depends_on` (`createSandbox.response.401.report.services.app.depends_on`; array, required) - `service` (`createSandbox.response.401.report.services.app.depends_on.service`; string, required) - `condition` (`createSandbox.response.401.report.services.app.depends_on.condition`; string, required) - `network` (`createSandbox.response.401.report.services.app.network`; object, required) - `aliases` (`createSandbox.response.401.report.services.app.network.aliases`; array, required) - `endpoint_mode` (`createSandbox.response.401.report.services.app.network.endpoint_mode`; string, required) - `drives` (`createSandbox.response.401.report.services.app.drives`; array, optional) — The Drives its instance mounts (`AppCreate.drives`): none, `[]`, where it names none. - `drive` (`createSandbox.response.401.report.services.app.drives.drive`; string, required) - `path` (`createSandbox.response.401.report.services.app.drives.path`; string, required) - `mode` (`createSandbox.response.401.report.services.app.drives.mode`; string, required) - `key_drives` (`createSandbox.response.401.report.services.app.key_drives`; array, optional) — The Drives each key's instance has of its own (`AppCreate.key_drives`): none, `[]`, where it gives none. - `name` (`createSandbox.response.401.report.services.app.key_drives.name`; string, required) - `path` (`createSandbox.response.401.report.services.app.key_drives.path`; string, required) - `size_bytes` (`createSandbox.response.401.report.services.app.key_drives.size_bytes`; integer | null, required) - format `int64` - `nocopy` (`createSandbox.response.401.report.services.app.key_drives.nocopy`; unknown, optional) — There only where it was given as `true`. - `runtime` (`createSandbox.response.401.report.services.app.runtime`; any of, optional) — Its runtime settings (`AppCreate.runtime`). `null`: none. - any of: `Runtime`, `null` - `traces` (`createSandbox.response.401.report.services.app.traces`; object, optional) — 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_rate` (`createSandbox.response.401.report.services.app.traces.sample_rate`; number, required) - min 0; max 1 - `trust_incoming` (`createSandbox.response.401.report.services.app.traces.trust_incoming`; boolean, required) - `volumes` (`createSandbox.response.401.report.volumes`; array, required) — The volumes of the project the services mount. - `model` (`createSandbox.response.401.report.volumes.model`; string | null, required) — Its name in the model. Null: made for a path a stateful service mounts with no volume named. - `name` (`createSandbox.response.401.report.volumes.name`; string, required) — Its name in the project. - `id` (`createSandbox.response.401.report.volumes.id`; string | null, required) — Null: not made yet (`to_make`). - pattern `^vol-` - `shared` (`createSandbox.response.401.report.volumes.shared`; boolean, required) — Several services mount it, or one with several instances: every instance of each mounts it at once. - `status` (`createSandbox.response.401.report.volumes.status`; string, required) — `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. - one of `"to_make"`, `"made"`, `"there"`, `"external"` - `used_by` (`createSandbox.response.401.report.volumes.used_by`; array, required) - `secrets` (`createSandbox.response.401.report.secrets`; array, required) — The secrets of the model that services are granted. - `model` (`createSandbox.response.401.report.secrets.model`; string, required) — Its name in the model. - `name` (`createSandbox.response.401.report.secrets.name`; string, required) — 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. - `there` (`createSandbox.response.401.report.secrets.there`; boolean, required) — Whether the project has it. An import (not a dry run) with one that is not there is refused 404 `secret_not_found`. - `used_by` (`createSandbox.response.401.report.secrets.used_by`; array, required) - `left_out` (`createSandbox.response.401.report.left_out`; array, required) — The services of profiles that are not turned on, which the import does not touch. - `name` (`createSandbox.response.401.report.left_out.name`; string, required) - `profiles` (`createSandbox.response.401.report.left_out.profiles`; array, required) - `absent` (`createSandbox.response.401.report.absent`; array, required) — The project's services that the model does not have: kept as they are. - `deploy` (`createSandbox.response.401.report.deploy`; string | null, required) — The deploy the import made (`GET /v1/deploys/{id}`). Null: a dry run, or nothing would get a version. - pattern `^dpl-` - `accounts` (`createSandbox.response.401.accounts`; array, optional) — With `sole_owner`: the accounts the user is the only owner of. - `id` (`createSandbox.response.401.accounts.id`; string, required) - pattern `^acct-[0-9a-hjkmnp-tv-z]{16}$` - `name` (`createSandbox.response.401.accounts.name`; string, required) ### 403 The credential may not do this. `needs_api_key`: a sandbox token cannot do this. `secret_host_not_allowed`: a secret would be sent to a host it may not go to: by `egress.inject` (the rules given, or a snapshot's), 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; the message says what it holds there and what it may. Nothing was made. #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.403.error`; object, required) - `type` (`createSandbox.response.403.error.type`; string, required) — 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. - `code` (`createSandbox.response.403.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.403.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.403.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.403.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.403.error.request_id`; string, required) — 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_url` (`createSandbox.response.403.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.403.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.403.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.403.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.403.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.403.exec_id`; string, optional) — 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_ms` (`createSandbox.response.403.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.403.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.403.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.403.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.403.image`; string, optional) — 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}$` - `build` (`createSandbox.response.403.build`; string, optional) — 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. #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.404.error`; object, required) - `type` (`createSandbox.response.404.error.type`; string, required) — 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. - `code` (`createSandbox.response.404.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.404.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.404.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.404.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.404.error.request_id`; string, required) — 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_url` (`createSandbox.response.404.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.404.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.404.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.404.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.404.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.404.exec_id`; string, optional) — 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_ms` (`createSandbox.response.404.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.404.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.404.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.404.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.404.image`; string, optional) — 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}$` - `build` (`createSandbox.response.404.build`; string, optional) — 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, or another sandbox took the one `project_address` names meanwhile; `sandbox_failed`: the sandbox's template holds its start command back (`TemplateBuildRequest.start_after_volumes`) and the command did not come up once the volumes were mounted: the message says what it printed last, and nothing is kept; `idempotency_key_reused`: the key was used with another body; `idempotency_in_progress`: the first request with the key is still running. `volume_restoring`: a volume it names is being made from a backup, or could not be. `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). #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.409.error`; object, required) - `type` (`createSandbox.response.409.error.type`; string, required) — 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. - `code` (`createSandbox.response.409.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.409.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.409.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.409.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.409.error.request_id`; string, required) — 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_url` (`createSandbox.response.409.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.409.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.409.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.409.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.409.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.409.exec_id`; string, optional) — 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_ms` (`createSandbox.response.409.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.409.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.409.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.409.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.409.image`; string, optional) — 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}$` - `build` (`createSandbox.response.409.build`; string, optional) — 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. #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.503.error`; object, required) - `type` (`createSandbox.response.503.error.type`; string, required) — 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. - `code` (`createSandbox.response.503.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.503.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.503.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.503.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.503.error.request_id`; string, required) — 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_url` (`createSandbox.response.503.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.503.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.503.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.503.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.503.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.503.exec_id`; string, optional) — 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_ms` (`createSandbox.response.503.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.503.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.503.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.503.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.503.image`; string, optional) — 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}$` - `build` (`createSandbox.response.503.build`; string, optional) — 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. #### Example ```json { "error": { "type": "string", "code": "string", "message": "string", "param": "string", "retryable": true, "request_id": "string", "docs_url": "string" }, "allowed_hosts": [ "string" ], "to": "string", "epoch": 1, "offset": 0, "exec_id": "string", "disk_ms": 0, "memory_ms": 0, "drives_ms": 0, "image_ms": 0, "image": "string", "build": "string" } ``` - `error` (`createSandbox.response.default.error`; object, required) - `type` (`createSandbox.response.default.error.type`; string, required) — 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. - `code` (`createSandbox.response.default.error.code`; string, required) — Which failure. The top-level `x-error-codes` table of this document says what each one means. - `message` (`createSandbox.response.default.error.message`; string, required) — For people. English. - `param` (`createSandbox.response.default.error.param`; string | null, required) — The field or query parameter at fault, when there is one. - `retryable` (`createSandbox.response.default.error.retryable`; boolean, required) — True when the same request may succeed later without anything else changing. - `request_id` (`createSandbox.response.default.error.request_id`; string, required) — 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_url` (`createSandbox.response.default.error.docs_url`; string | null, required) — The node's `--docs-url` with the code appended, or null. - `allowed_hosts` (`createSandbox.response.default.allowed_hosts`; array | null, optional) — With `secret_host_not_allowed`: the hosts the secret may go to, as the secret has them; null where it was given none. - `to` (`createSandbox.response.default.to`; string | null, optional) — With `moved` and `sandbox_moved`: the node the sandbox was released to, as the control plane named it, or null. - `epoch` (`createSandbox.response.default.epoch`; integer, optional) — 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`; min 1 - `offset` (`createSandbox.response.default.offset`; integer, optional) — 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`; min 0 - `exec_id` (`createSandbox.response.default.exec_id`; string, optional) — 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_ms` (`createSandbox.response.default.disk_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the disk as of the sleep; null where it did. - min 0 - `memory_ms` (`createSandbox.response.default.memory_ms`; number | null, optional) — With `copy_behind`: how long the release waited for the store to hold the memory image of that sleep; null where it did. - min 0 - `drives_ms` (`createSandbox.response.default.drives_ms`; number | null, optional) — 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. - min 0 - `image_ms` (`createSandbox.response.default.image_ms`; number | null, optional) — 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. - min 0 - `image` (`createSandbox.response.default.image`; string, optional) — 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}$` - `build` (`createSandbox.response.default.build`; string, optional) — With `build_missing`: the build of Firecracker that wrote the sandbox's memory, which this node does not keep. - pattern `^[0-9a-f]{16}$` Source: https://glac.ai/docs/api/sandboxes/create/index.md