Compute | Dokumentacja Glac

What every product runs on. Any OCI image, each instance a Firecracker microVM of its own; instances with a key or without, when an instance sleeps and what wakes it, and how Cube and Sandbox sit on it.

Ta strona nie jest jeszcze przetłumaczona na polski: oto jej wersja angielska.

Compute is what the products of Glac run on. It runs any OCI image, public or private (the kind docker builds and registries serve), in instances: each instance is a Firecracker microVM of its own. Cube and Sandbox are products built on it, and Drive gives its instances disks that outlive them.

Instances

An instance is the one thing that runs: whatever a Cube or a sandbox runs, runs in an instance.

A virtual machine of its own. The image’s layers are unpacked into a root file system, and Firecracker boots it with the platform’s kernel: there is no Docker, and no second virtual machine, in between. Commands and files reach an instance through an agent inside it, not through its network. Everything in it belongs to one project.
A copy of a template. A template is an image booted once and saved: its memory, its devices and its disk. Instances are copies of it, so a program the template started is already running in each, and the memory it uses is shared until an instance changes it. A Cube’s instances are copies of its version’s template. The first sandbox made from an image waits while the platform pulls the image and builds its template; the ones after it are copies.
Its size. vCPUs and memory, never more than the plan allows: 2 vCPU i 4 GiB on Free, 8 vCPU i 16 GiB on Paid. Without a size, each product gives its own: see making a sandbox and what a version is.
With a key or without. An instance without a key is one of many, and the platform picks it: a Cube’s requests go to the instances of its current version, which are started when requests come. An instance with a key is named, and whatever carries the key reaches that one instance. A sandbox is a keyed instance, named by its id or its name. A Cube can have keyed instances too: requests that carry a key (in a header, or a segment of the path) all go to that key’s own instance (keyed instances).

Stateless or stateful

Compute can keep state or not, instance by instance.

A sleeping instance keeps what it had: its memory, its processes, its disk and its network place. When it wakes, open connections carry on. sleep_tier says how it sleeps: paused (held in the host’s memory), saved (its memory saved on the host) or disk, where only its disk is left: the next call boots it from disk, and what was running is gone.
Stateless: a Cube’s instances without a key (unless it keeps data on a Drive of its own, below). An instance that nothing has kept awake for delete_after_ms (one hour unless you say less) is deleted, and the next request makes a new one from the template. Keep nothing in one that must last.
Stateful: the instances that are kept. A sandbox stays until you delete it, or until a rule you set deletes it (expires_at, delete_after_idle_ms, or the project’s delete_after_idle_days); sleeping alone deletes nothing. A Cube’s keyed instance is kept with its memory and disk for the next request with its key, and keys.delete_after_idle_ms deletes it after it has slept that long. A Cube with a Drive of its own has exactly one instance, kept until you delete it, on the machine that holds the Drive (a service that keeps data).
What must outlive any instance goes on a Drive, which is copied to its region’s object store as it is written.

Regions

There are three regions, na, eu and ap. A sandbox and a Drive are each made in one; a Cube runs in every region it names, and a request is answered in the region it comes in at. Where each thing is made, and what happens when a region cannot take it, is on regions.

Sleep and wake

An instance that is idle goes to sleep, and whatever needs it next wakes it: there is no wake call. What counts as idle depends on the product:

	A Cube’s instance	A sandbox
Awake while	It answers a request (an open HTTP/2 stream, such as a gRPC call, counts until it ends), an API call uses it, or a program in it holds it awake. CPU, packets, open connections and timers do not count.	A call waits on it, its programs use 2% of one core or more on average, packets cross its network link, it holds a TCP connection to the outside, a timer is due within 5 seconds, or a program in it holds it awake (when it sleeps).
Sleeps after	A wait picked from the app’s traffic, at most `sleep_after_ms`: 3 000 unless you say (up to 600 000).	`sleep_after_seconds` idle: 30 unless you say, at least 1, or `null` for never.
Woken by	The next request, or new data on a WebSocket it keeps open.	Anything that needs it: a command, a file, a request on a link to one of its ports, a connection to it on the project’s network, new data on a connection it has, a key pressed in its terminal, a snapshot, a fork, a timer.
Deleted	Without a key: when nothing has kept it awake for `delete_after_ms`, one hour unless you say less.	When you delete it, or by `expires_at`, `delete_after_idle_ms` or the project’s `delete_after_idle_days`.

Holds. A program that still has work after it has answered (a queue to drain, a write to finish) can keep its instance awake by itself through the Unix socket /run/sbx/awake, for sleep_hold_max_ms at the most (scale.sleep_hold_max_ms on a Cube; 30 000 ms unless you say). How, and the code: keeping it awake from inside.
How long a wake took. An API call that had to wake an instance says so, in milliseconds, in its Server-Timing: wake;dur=… header. A Cube’s log says it on the line of each request that woke an instance (logs and metrics).

When a machine is lost

A machine that stops answering, and is not heard from for a while, is judged lost, and its sandboxes and keyed instances are taken over on another machine: of the same region where one can take them, else of the next region. They come from the object store, as the machine last copied them there:

One that was asleep comes back with its memory and its processes, as it was when it went to sleep.
One that was awake starts again from its disk: what was running is gone, and what it wrote is there as far as it was copied (a Drive says how far). It is woken on its new machine once the takeover is done, without waiting for a request. With checkpoints it goes on from its newest one instead, with its processes.
Not taken over: a sandbox with a volume on the machine’s own disk, which the object store has no copy of, and every instance of a machine that copies nothing to an object store; they are there again when the machine is.

Meanwhile, requests to them and calls that need them answer 503 node_unavailable, retryable. Each one taken over is a sandbox.moved event in the project, with reason host_lost and with_processes saying whether it came with its processes. An instance of a Cube without a key is not taken over: the app’s other machines make new ones.

When a whole site is lost and the control plane was there, its second copy, in another site, takes over first. Until it has, API calls answer 503 standby, retryable, with Retry-After.

A machine that comes back cannot speak to the control plane until an operator lets it in again, and does not answer for what may have been taken over: from the moment its lease ran out, a request for one of its sandboxes waits three seconds and is answered 503 fenced. A keyed instance, or a sandbox with a volume, is held still meanwhile; any other sandbox’s machine goes on running, unheard. Once the control plane answers, what was taken over elsewhere ends on it (409 moved), and what was not is served there again. No sandbox answers from two machines.

Cube and Sandbox

The two products use the same instances in two ways:

Cube runs an image as a service with its own address: a Cube, which the API calls an app (/v1/apps). Each deploy makes a version, and the version’s instances are copies of its template; the platform starts them when requests come and keeps none when none come. Every Cube is a service of its project: services find each other on the project’s private network, deploy together, and can be imported from a Compose file (services and Compose).
Sandbox gives AI agents keyed instances to work in, made and used through the API (/v1/sandboxes): you run commands in a sandbox, read and write its files, open a terminal in it, take snapshots of it and fork it, connect to it with SSH, and set the rules of its network.
One kind of instance underneath. A Cube’s instances are in the project’s list of sandboxes (label app), are metered like any sandbox, and you can run commands in them.

What it costs

Every instance is metered the same way, whichever product it belongs to: awake, the CPU time it uses and the memory it holds (in 128 MiB steps, by the millisecond); asleep, no CPU: one paused in the host’s memory still pays for that memory, and one whose memory is saved pays only for what it keeps, by the GB-month. A plan’s limits on what is awake at once count sandboxes and Cubes’ instances together, in all the projects of the account. See pricing and plans and limits.