Skip to content


On KraftCloud, an image is comprised of your application files and binaries, as well as a highly specialized and performant unikernel. We store these together as an OCI image and distribute them worldwide using low-latency metro interconnects.

As images deployed to KraftCloud are lightweight; transport is fast, and distributing new and updated production-ready applications takes only milliseconds to propagate (caveat: clearly if the application itself is large, the overall image will be large as well).

Image Name Reference

We follow the OCI Distribution Specification for naming and referencing images. When referencing an image you can either reference it by its tag:


or by its SHA256 checksum:


Where <USER> is the name of your user account, <APP> is the name of the application you want to start, <TAG> specifies a label applied to this application (e.g., latest), and <CHECKSUM> represents the digest of a specific version of the image.

Since the latest version of an application may change when an update is pushed, KraftCloud computes a SHA256-based digest of the image to uniquely identify it. Whenever you create a new instance from an image, KraftCloud translates the tag to the image’s digest and pins the instance to this particular version. That is why GET /v1/instances reports a digest instead of the tag originally used to create the instance.

Applications under the namespace of your user account can only be accessed by your user and are private to you. In addition to private images, there are official images published by KraftCloud which are accessible by just their name:


API Endpoints

The KraftCloud Images REST API provides the following endpoints:

GET/v1/images/listList existing images

In the following, the API endpoints are specified relative to this base URL:

With X being the IATA metro code. We use fra0 as an example in the documentation. See the introduciton for more information on how to connect to the API.

List Existing Images

Lists existing images. You can filter by various aspects such as showing only your personal images or one or more specific digests or tags. The returned images fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.


GET /v1/images/list

Query ParameterTypeDefaultRequiredDescription
namespace1stringFilter images by namespace
taggedflagList only tagged images

1Set the namespace to your KraftCloud account name to list only your personal images. It can be official for listing only the official ones. In addition, the namespace can include the app name. For example, ${KRAFTCLOUD_USER}/myapp to list all your myapp images.

Body ParameterTypeDefaultRequiredDescription
digeststringImage digest to lookup
tagstringImage tag to lookup

Example of listing all available images:

curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \

Example of looking up all your tagged images:

curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
"\=${KRAFTCLOUD_USER}\&tagged" \

Example of looking up the image for a specific digest:

curl -X GET \
-H "Authorization: Bearer ${KRAFTCLOUD_TOKEN}" \
-H "Content-Type: application/json" \
"" \
-d "{
'digest': '${KRAFTCLOUD_USER}/myapp@sha256:c4c2919...f03db26'


The response is embedded in a JSON object as described in API Responses.

digeststringImage digest to uniquely identify this image
tagsarray of stringsTags referencing this image
initrdboolIndicates if the image comes with an init ramdisk
size_in_bytesintTotal size of the image on disk in bytes including the initrd, if any
argsstringDefault application arguments of the image. Dismissed if the instance specifies application arguments
kernel_argsstringUnikraft kernel arguments hardcoded into the image. Prepended to the kernel arguments set by KraftCloud
Status: 200 OK
"status": "success",
"data": {
"images": [
"digest": "${KRAFTCLOUD_USER}/myapp@sha256:c4c2919...f03db26",
"tags": [
"initrd": true,
"size_in_bytes": 2487552