Roll a sandbox back to a snapshot

sbx- and 16 characters; valid as a DNS label.

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.

How long a connection on one of awake_ports may carry nothing before the node closes it (SandboxCreate); null: never for that.

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.

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.

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.

Its own proxy (SandboxCreate's proxy): its address and the user name it is asked with, never its password. Null where it has none.

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).

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.

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).

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.

Its checkpoints while it runs (SandboxCreate's checkpoint), and how they go; null where it has none.

The names of the variables of secret_env it was made with, in order; never a value. Empty for one made with none.

The name the caller gave it, or null.

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.

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.

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.

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.

The OCI image reference the sandbox goes back to. Null only on a node whose base template was built from a disk file.

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.

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).

Ports whose preview URL needs no signature and no token. Duplicates are kept as given.

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.

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.

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.

When the sandbox deletes itself (or what on_expiry says). Null: never.

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.

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.

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.

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.

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.

The time of day, in UTC, at which the node wakes it every day while it rests (SandboxCreate); null: none.

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.

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.

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.

Whether the guest kernel keeps its mitigations against speculative execution (guest_mitigations at creation).

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.

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.

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.

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).

What the sandbox has used and uses.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

With app_id: what it is found by among the app's instances, its name, or its id where it has none.

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.

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/).

Signs this sandbox's preview links. Absent (not null) when the caller is a sandbox token.

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.

Whether the snapshot is in the object store the node copies its disks to, complete (every part of it there and its index written last), so that a node of the site that copies to the same store can make a sandbox from it, fork from it and roll a sandbox back to it. A node that copies its disks (--upload) publishes every snapshot it takes, in the background, a second or two after the call that took it answered. Its disk is not copied: the publication pins the state the sandbox's own disk had in the store at the snapshot, and carries only the blocks that were not there yet; its memory goes as a sleep's image does. False until then, and for good for a snapshot of a node that copies to no store, one taken before snapshots were published, and one of a machine whose memory is not in layers: such a snapshot is used on its node, as ever.

When its publication was complete. Null: it is not in the store.

How its publication stands: pending (taken, not asked of the node's uploader yet: its files are being forced), replicating (the uploader is at it), replicated, failed (the last try failed, and the node tries again, twenty seconds later and twice as long after each failure, at most a quarter of an hour), not_replicable (it is never published, for the reasons under replicated).

The egress rules of the sandbox at the instant the snapshot was taken. A sandbox created from the snapshot starts with them unless the call gives egress; a sandbox restored to the snapshot keeps the rules it has.

Whether a sandbox made from the snapshot on this node continues from the snapshot's instant, processes included. False: the snapshot's memory was saved by a build of Firecracker the host does not keep, or with other settings for the machine's devices than the node starts machines with now (or the snapshot is lost); one that a kept build saved is loaded by that build (Node.firecrackers). The snapshot is kept as it is, and is loadable again on a node that is started with what saved it. Meanwhile a sandbox created from it, or rolled back to it, gets the snapshot's disk and starts from that: nothing that ran in the snapshot runs in it, and its host_failure says so (cause node_changed).

ready: the call that takes a snapshot returns when it is complete. lost: the node's host went down hard before the snapshot's files were on its disk (the node writes them there within a second or two of the call's answer, without holding the call up); it is listed so that its owner knows, sandboxes cannot be created from it or restored to it (409 snapshot_lost), and it can be deleted.

The sandbox it was taken of.

The image that sandbox goes back to.

What it holds, in bytes, fixed when it is taken: what its sandbox had of its own at that moment (the pages of its memory that are not its template's, the state of its devices, the layer of its disk over the image) and nothing of the template or the image. The three parts a sleeping sandbox is counted as keeping. It is the same whatever else exists: another snapshot of the sandbox holds its own number, and deleting one changes no other's. A node counts a snapshot as keeping this for as long as it is there (a lost one as keeping nothing).

When it deletes itself. Null: never.