Briq

A briq is one OCI image running on its own microVM, with an internal address, optional ports and volume, a size, and a sleep window.

Fields

A briq spec

What a recipe renders. Over REST, send your own as spec to POST /v1/briqs. briq_run takes every field but expose, plus expose: "public" | "private" to publish the briq's single port.

{
  "name": "db",
  "image": "postgres:16",
  "env": { "POSTGRES_PASSWORD": { "secret": "POSTGRES_PASSWORD" }, "POSTGRES_DB": "app" },
  "ports": [5432],
  "size": "small",
  "volume": { "mount": "/var/lib/postgresql/data", "gb": 2 },
  "healthcheck": { "cmd": ["pg_isready", "-U", "postgres"] },
  "sleep": "1h"
}

With a healthcheck, the briq is running only once the command succeeds. Without one, running means the process started: if it exits a moment later, the briq stops and its status says how (see Lifecycle). A probe should ask 127.0.0.1, not localhost: inside a briq, localhost is ::1, which a server listening on IPv4 only refuses.

Files

files puts files in place before the process starts: your app's sources, a config file. Text goes as it is, binary as { "base64": "…" } (padded, on one line; base64 whose length shows it was cut short is refused); 256 KB in all.

{
  "name": "web",
  "image": "python:3.12-slim",
  "files": { "/app/server.py": "from http.server import …" },
  "cmd": ["python", "/app/server.py"],
  "ports": [8080]
}

They are written again whenever the process starts over (a restart, a cold start), so the spec stays their source of truth: an edit made inside the briq to one of them lasts until then. A resume from a memory snapshot (nano and small sizes) is not a start over: the process carries on where it was, files included. A fork gets them too. For anything bigger, fetch it from inside the briq (git clone, curl).

• Paths are absolute, without . or .. segments: /app/server.py, not server.py.
• 64 files and 256 KB in all.
• Status lists them by path and size; their content is not shown again, and the audit log records the path and size only.
• briq_files_put on one of them answers with a warning: the change lasts until the next start.

Disk

A briq keeps its disk. Files written anywhere in it, by its process, briq_exec or briq_files_put, are still there after a stop, a start, a restart or an expose. A destroy removes them.

A volume is the durable part: use one for data you cannot afford to lose, such as a database's files. Its size is gb, 2 by default and up to 500, set at creation and counted toward your plan's disk; a recipe takes it as diskGb. The rest of the disk can be reset to the image during the provider's host maintenance, and a fork copies the volume only.

What a briq is not

• Not a container on a shared kernel: each briq is a Firecracker microVM.
• Not a place for data you cannot lose outside a volume, and nothing survives a destroy.
• Not reachable from the internet until you publish it (expose on briq_run, or briq_expose).