Cubes documentation

Cubes gives every agent its own build sandbox — a cube — that wakes for builds and sleeps between them. This page documents the cube lifecycle, and the small HTTP API the console uses.

The cube lifecycle

cold — the cube exists as a snapshot: toolchain image, caches, nothing running. Free.
waking — a build arrived; the cube thaws in milliseconds with caches warm.
building — the only state that meters. Billed per second of wall clock.
drowsy — the build finished; the cube lingers briefly in case another lands.
asleep — frozen again. Free. A sleeping cube keeps its caches indefinitely on Boulder and Mountain, for 24 hours on Pebble.

HTTP API

The Cubes backend is one function with a public URL. It serves this site and three JSON endpoints:

Route	Method	What it does
`/api/health`	GET	Liveness: returns `{"ok":true,"service":"cubes"}` plus whether the PDF and support integrations are configured.
`/api/invoice`	POST	Body `{"name","plan","cubeHours"}`. Typesets a usage invoice in LaTeX, renders it through the platform catalog's `latex-to-pdf` service, and returns `application/pdf`.
`/api/support`	POST	Body `{"subject","message","contact?"}`. Files a ticket into the platform's `/_lola/support` channel with `source: "cubes"`.

Render an invoice from the command line

curl -X POST https://cubes.abot.at/api/invoice \
  -H 'content-type: application/json' \
  -d '{"name":"Acme Agents Ltd.","plan":"boulder","cubeHours":342.5}' \
  -o invoice.pdf

File a support ticket from the command line

curl -X POST https://cubes.abot.at/api/support \
  -H 'content-type: application/json' \
  -d '{"subject":"cube stuck drowsy","message":"cube-b7 will not fall asleep"}'

How Cubes itself is deployed

Cubes is a tenant of the sola-os minicloud (lola). The whole product is:

one Node function (handler.mjs, zero dependencies) deployed as a zip Lambda with a function URL — it serves the site and the API;
one catalog service, latex-to-pdf, deployed into the Cubes account from the platform catalog — it does the PDF typesetting;
the platform support channel, which receives Cubes' tickets.

That is the point of the demo: a real app, on real platform primitives, small enough to read in one sitting.