Registries
Unikraft Cloud uses a central OCI registry at index.unikraft.io to store images.
Every image you build and push lands in this registry under your account's namespace.
When you start an instance, the platform pulls the image from this registry automatically.
Each node has a local registry also running for directly pushing to a specific node.
These registries have the address formatted as index.<node-name>.unikraft.cloud.
The main advantage of pushing to a node's registry is that it avoids the round trip to the central registry.
This speeds up deployments and reduces bandwidth usage.
Directly pushing to a node's registry or using the central registry is interchangeable. The platform handles synchronization between them.
Limited Access
The local registry is only available in BYOC or on-prem Unikraft Cloud installations.
Temporary storage
Do not treat a node's local registry as permanent storage.
The platform cleans up its images over time, so push anything you need to keep to the central registry at index.unikraft.io.
Image naming
The platform addresses images using the standard OCI reference format:
For example:
The <my-org> segment is your Unikraft Cloud organization, available as the UKC_USER environment variable in most guides.
Tags are arbitrary strings.
The platform defaults to latest when you don't specify a tag.
You can also refer to images by digest to pin to an exact version.
Authentication
Registry authentication uses the same API token as the rest of the platform.
The new CLI uses profiles, while the legacy CLI reads UKC_TOKEN directly.
The UKC_TOKEN and UKC_METRO environment variables are only used by the legacy CLI.
When using external registries (e.g. ghcr.io), authenticate explicitly:
You don't need to login to the central or node registries.
Pushing images
Via unikraft build (recommended)
The simplest way to push an image is to use the CLI to build, package, push, and start an instance in one flow:
Via kraft pkg --push
For the legacy CLI, package using the --push flag:
Listing images
There may be a delay of a few minutes between pushing or removing an image and the image list reflecting the change.
Removing images
You can remove images with specific tags, or all tags at once:
Kernel layer deduplication
An image has two OCI layers: a kernel layer and a rootfs layer. When you push an update to an existing image, the CLI checks whether the kernel layer is already present in the registry and skips re-uploading it. Only the rootfs layer travels over the wire. This makes iterative pushes faster and cheaper on bandwidth.
ROMs follow the same packaging system but go out without a kernel layer. They only have a rootfs. They appear in the image list alongside regular images.
Instance creation
When creating an instance directly from an existing image, reference it by tag or digest:
Learn more
- Images: build, package, and deploy workflow.
- The CLI reference and the legacy CLI reference.
- Unikraft Cloud's REST API reference.