images
The images group is the catalog of OS images and ramdisks that deploys write to disk. An image is registered by its digest and source URL, never uploaded, and a signature from a signer on the tenant's or the platform's allowlist marks it verified. Unsigned images stay private to their tenant; only verified images can be made public. See [Profiles and images](/docs/guides/bare-metal/profiles-and-images).
The images group is the catalog of OS images and ramdisks that deploys write to disk. An image is registered by its digest and source URL, never uploaded, and a signature from a signer on the tenant's or the platform's allowlist marks it verified. Unsigned images stay private to their tenant; only verified images can be made public. See Profiles and images.
All 4 methods are served by this release.
| Method | Kind | Authorization | Phase | Status |
|---|---|---|---|---|
register | mutation | compute:images:publish @ compute-tenant or compute:images:publish @ compute-fleet | v0.2 | registered |
get | read | compute:images:read @ compute-image | v0.2 | registered |
list | read | compute:images:read @ compute-tenant + items | v0.2 | registered |
promote | mutation | compute:images:publish @ compute-image | v0.2 | registered |
register
POST /api/compute/images/register
Records an image by ref (name@version), format, digest and https:// or oci:// source in the tenant's catalog; with a valid signature it is marked verified.
- Decided as
compute:images:publishon the tenant. signatureandsignerIdgo together. The signature must verify against that signer on the tenant's allowlist or the platform's, elseINVALID_INPUT.- A
ramdiskmust be signed by a platform signer (INVALID_INPUTotherwise). CONFLICTwhen the tenant already has thatref, so a repeated call does not create a second image.
The new image is private. Site agents whose pools pre-warm this ref (policy.prewarmImages) get their desired state refreshed.
- Kind: mutation
- Authorization:
compute:images:publish@compute-tenantorcompute:images:publish@compute-fleet - Module:
provision - Phase: v0.2 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
ref | string | yes | 1-200 characters |
kind | one of os, ramdisk | default "os" | |
format | one of raw, qcow2, iso | yes | |
compression | one of none, zstd, gzip | default "none" | |
sha256 | string | yes | 1-64 characters; matches ^[0-9A-Fa-f]{64}$ |
sizeBytes | integer | at least 0 | |
source | string | yes | 1-2048 characters |
signature | string | 1-1024 characters | |
signerId | string | 1-128 characters |
get
POST /api/compute/images/get
Returns one image the tenant owns, or a public one, by its img_ id.
NOT_FOUND when the image does not exist, is deleted, or belongs to another tenant and is not public.
- Kind: read
- Authorization:
compute:images:read@compute-image - Module:
provision - Phase: v0.2 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
imageId | string | yes | at most 56 characters; matches ^img_[0-9a-hjkmnp-tv-z]{26,52}$ |
list
POST /api/compute/images/list
Returns a page of the tenant's own images and public ones, ordered by ref, optionally filtered by kind (os or ramdisk).
limit defaults to 50 and is at most 200; pass the returned cursor to read the next page.
- Kind: read
- Authorization:
compute:images:read@compute-tenant+ items - Module:
provision - Phase: v0.2 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
kind | one of os, ramdisk | ||
limit | integer | 1-200; default 50 | |
cursor | string | at most 256 characters |
promote
POST /api/compute/images/promote
Makes a verified image the tenant owns public, so every tenant can read and deploy it.
Decided as compute:images:publish on the image. An unsigned image is INVALID_STATE; an image the tenant does not own is NOT_FOUND. Promoting an image that is already public returns it unchanged. Site agents whose pools pre-warm this ref get their desired state refreshed.
- Kind: mutation
- Authorization:
compute:images:publish@compute-image - Module:
provision - Phase: v0.2 (registered)
Input
| Field | Type | Required | Constraints |
|---|---|---|---|
tenantId | string | yes | at most 128 characters; matches ^[A-Za-z0-9._:-]{1,128}$ |
imageId | string | yes | at most 56 characters; matches ^img_[0-9a-hjkmnp-tv-z]{26,52}$ |
Better Compute is created by Sean Filimon
Last updated
fleet
The fleet group manages a tenant's platform objects as one FleetConfig document: sites, provider accounts, pools, owner quotas, offers and flavors. `plan` diffs a document against what exists, `apply` runs the plan through the owning modules' own methods, and the applied document is kept so that drift from it is reported. Every method decides `compute:fleet:admin` on the fleet scope. See [Fleet configuration](/docs/guides/fleet-config).
instances
Instances are VMs in a VPS pool: hosted pools place them on a host through capacity, and provider pools create them through the pool's provider account. After `create`, every call only changes `desiredState`; the `vps.instances` reconciler converges the instance and publishes `instance.*` events as its `state` moves. Instances are also the sandbox primitive today. See [Instances](/docs/guides/vps/instances).