---
title: "Compute"
description: "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."
---

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

# Compute

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](https://firecracker-microvm.github.io/) microVM of its own. [Cube](/docs/cube/) and [Sandbox](/docs/sandbox/) are products built on it, and [Drive](/docs/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 vCPUs and 4 GiB on Free, 8 vCPUs and 16 GiB on every paid plan. Without a size, each product gives its own: see [making a sandbox](/docs/sandbox/commands/#making-a-sandbox) and [what a version is](/docs/cube/versions/#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](/docs/cube/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](/docs/cube/services/#a-service-that-keeps-data)).
- **What must outlive any instance** goes on a [Drive](/docs/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](/docs/platform/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](/docs/sandbox/sleep/#when-it-sleeps)). |
| Sleeps after | `sleep_after_ms` idle: 100 ms 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](/docs/sandbox/sleep/#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](/docs/platform/logs/)).

## 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](/docs/drive/concepts/#how-durable-a-write-is) says how far). It is woken on its new machine once the takeover is done, without waiting for a request. With [checkpoints](/docs/sandbox/sleep/#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`](/docs/errors/#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`](/docs/errors/#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](/docs/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](/docs/cube/services/)).
- **[Sandbox](/docs/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 steps of 128 MiB); 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](/docs/platform/pricing/) and [limits](/docs/platform/limits/).

Source: https://glac.ai/docs/platform/compute/index.mdx