Concepts
Briq
One running OCI image on its own microVM.
A briq is the core object: one OCI image running on one microVM, with an internal hostname, optional ports, an optional volume, a size, and a stop time.
Fields
| Field | Notes |
|---|---|
id | bq_ followed by 12 base32 characters, e.g. bq_7kq2m9x1p4ab |
stackId, name | The name is DNS-safe (lowercase, digits, dashes, up to 32 chars) and unique within the stack: db, api, redis |
image | Fully qualified OCI reference. The digest is pinned after the first pull so a briq never silently changes image |
cmd, entrypoint, env, ports | As in a container spec. env values are strings, or { secret: NAME } for generated, write-only secrets |
size | nano, small, medium or large. See Cost |
state | creating, running, stopped, destroyed, or error |
internalHost | <name>.<stack>.<team>.internal, resolvable from any briq in the same team network |
endpoints | Public exposures created with briq_expose, each with port, mode and url |
ttlMinutes, stopsAt | Hard deadline, used or not. Default 480 minutes, maximum 10080 (one week). Extend with briq_extend |
idleMinutes, idleStopsAt, lastUsedAt | Auto-stop after this long with nothing touching it. Default 60, 0 disables. See Lifecycle |
costCentsSoFar | Metered per second while running; denormalised so every response can show it |
A briq spec
This is what a recipe renders, and what you pass to briq_run when you do not use a recipe:
{
"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": 10 },
"healthcheck": { "cmd": ["pg_isready", "-U", "postgres"] },
"ttlMinutes": 480,
"idleMinutes": 60
}Validation is a Zod schema in @briq/core, the single source of truth shared by the API, the
MCP tools, the SDK and these docs.
What a briq is not
- Not a container in a shared kernel. Each briq is a Firecracker microVM.
- Not persistent by default. Without a
volume, the rootfs is discarded on destroy. Stopped briqs keep their rootfs at the storage rate. - Not reachable from the internet unless you call
briq_expose.