Borealis Docs

Images, registries, and templates

Prepare custom runtime images, check readiness for a compute profile, and reuse published revisions.

Prepare a custom base image

Open Images in the Borealis app and use Prepare base image.

  1. Select Import registry image or Build Dockerfile and context.
  2. For a registry import, provide an immutable SHA-256 image reference such as registry.example/app@sha256:…. Select a registry connection for a private image. For a build, upload a build-context tar archive and give the Dockerfile path inside it.
  3. Select the architecture: x86_64 or aarch64.
  4. Set VM size to prepare: vCPUs, memory in MiB and disk capacity in GiB. Other sizes need their own preparation.
  5. Enable nested containers only when the workload needs them, then choose Prepare image.

The operation has its own build ID and progress. Follow the build through assessment, any required approval and publication. An accepted request or a completed download does not mean the image is ready to allocate a VM.

The public API exposes creation and inspection at /api/v1/runtime-image-builds and /api/v1/runtime-image-builds/{buildId}. Approval is a separate permission from building. Inspect a failure before retrying; preserve the original idempotency key when recovering an uncertain request.

Stage the revision for the intended resources

A published runtime image has an immutable template ID and revision. Before starting a custom-image VM, stage that exact revision for the CPU, memory, root-disk size and placement you intend to use:

POST /api/v1/runtime-image-templates/{templateId}/{revision}/stage

Example request body, with HOST_POOL_ID replaced by an authorised pool UUID:

{
  "placement": { "hostPoolId": "HOST_POOL_ID" },
  "resources": { "vcpu": 2, "memoryMiB": 4096, "rootDiskGiB": 16 }
}

Inspect the returned pool readiness. ReadyHosts identifies eligible prepared hosts for that revision and resource shape. A different shape needs separate preparation. Staging into another placement can reuse the published image while preparing it on eligible capacity there.

If allocation reports runtime_image_staging_required, stage the selected revision and shape and wait for readiness before trying again. Image publication alone does not establish host readiness, and a ready image does not reserve unlimited compute capacity.

Private registries and credentials

Use the authorised registry connection for the source image. Keep passwords and tokens out of image references, build contexts, templates and logs. Check registry access when assessment or import cannot retrieve the image; check the image’s architecture and startup configuration when it cannot run.

For container-registry CLI operations, inspect borealis registry create --help for the installed command’s protected input options, including --secret-file and --secret-stdin where offered.

Distinguish templates from recovery checkpoints

An image revision supplies a reusable base. A Runtime v2 template can also capture and publish an eligible source machine for creating a distinct VM. Template publication and activation use /api/v1/runtime-templates; these are separate from the runtime image-build routes.

Restoring an ordinary recovery checkpoint continues the same logical VM. It is not a way to clone it under a new identity. Use the template workflow when you need a reusable starting point for another machine.

Legacy container templates save creation defaults such as image, command, variables and resources. Editing those defaults does not update running containers. See Snapshots and durability for the different state guarantees.

Connect the resulting machines

Attach VMs that need to communicate to a private network. Image preparation does not grant network membership or create a service registration. Verify both application readiness and connectivity after allocation.