Instances

This document describes the Unikraft Cloud Instances API (v1) for managing Unikraft instances. An instance is a MicroVM running a single instance of your app.

Code
const inst = await ukc.metro("fra").instances
  .create({ image: "nginx:latest", memory_mb: 256, autostart: true })
  .wait({ state: "running" });

Instance states

An instance can be in one of the following states:

Unikraft Cloud reports these as instance state values via the endpoints. You can visualize these states with the CLI. Here is an example of an instance that's in stopped state:

Code
unikraft instance get httpserver-go121-taud8

Code
metro:           fra
name:            httpserver-go121-taud8
uuid:            bd281cc4-7640-4cbc-af48-5a44c2bd7b74
state:           standby
image:           <my-org>/httpserver-go121
resources:
  memory:        256MiB
  vcpus:         1
service:
  name:          floral-sun-54ixkmi6
  uuid:          d20c8a02-53a8-4917-8c25-94b99ab59a88
  domains:
  - fqdn:        floral-sun-54ixkmi6.fra.unikraft.app
networks:
- uuid:          16ca6566-a368-45d3-b759-3abf0cc37d03
  private-ip:    10.0.0.37
  mac:           12:b0:0a:00:00:25
timestamps:
  created:       6 days ago
scale-to-zero:
  enabled:       true
  policy:        on
  cooldown-time: 1s
stop:
  reason:        platform stop
  exit-code:     1

You can retrieve even more instance details via the API:

GET /instances/bd281cc4-7640-4cbc-af48-5a44c2bd7b74
curl -X GET \
  -H "Authorization: Bearer ${UKC_TOKEN}" \
  -H "Accept: application/json" \
  https://api.fra.unikraft.cloud/v1/instances/bd281cc4-7640-4cbc-af48-5a44c2bd7b74

{
  "status": "success",
  "data": {
    "instances": [
      {
        "status": "success",
        "uuid": "bd281cc4-7640-4cbc-af48-5a44c2bd7b74",
        "name": "httpserver-go121-taud8",
        "created_at": "2026-05-28T13:53:40Z",
        "state": "standby",
        "private_fqdn": "httpserver-go121-taud8.internal",
        "image": "oci://unikraft.io/<my-org>/httpserver-go121:latest@sha256:7785ebdf6c1ffaf05c3beab4cffc2548790c088233a0ee51ac5d047e21e43d77",
        "memory_mb": 256,
        "vcpus": 1,
        "stop_reason": 39,
        "exit_code": 1,
        "stop_code": 33024,
        "restart_policy": "never",
        "scale_to_zero": {
          "enabled": true,
          "policy": "on",
          "cooldown_time_ms": 1000,
          "notify_time_ms": 0,
          "stateful": false
        },
        "boot_time_us": 75698,
        "net_time_us": 79067,
        "start_count": 3,
        "started_at": "2026-05-28T13:54:43Z",
        "stopped_at": "2026-05-28T13:54:45Z",
        "uptime_ms": 47521,
        "service_group": {
          "uuid": "d20c8a02-53a8-4917-8c25-94b99ab59a88",
          "name": "floral-sun-54ixkmi6",
          "domains": [
            {
              "fqdn": "floral-sun-54ixkmi6.fra.unikraft.app"
            }
          ]
        },
        "network_interfaces": [
          {
            "uuid": "16ca6566-a368-45d3-b759-3abf0cc37d03",
            "private_ip": "10.0.0.37",
            "mac": "12:b0:0a:00:00:25"
          }
        ],
        "private_ip": "10.0.0.37",
        "volumes": []
      }
    ]
  }
}

Stop reason

To understand why Unikraft Cloud stopped an instance or is shutting it down, it provides information about the stop reason. You can retrieve this information via the GET /instances endpoint when an instance is in the draining, stopping, stopped or standby state.

The stop_reason contains a bitmask that tells you the origin of the shutdown:

For example, the stop_reason has the following values in these scenarios:

Exitcode

The app exit code is what the app returns upon leaving its main entry point. The encoding of the exit_code is app specific. See the documentation of the app for more details. An exit_code of 0 indicates success or no failure.

Stopcode

If bit 0 [K] is set in stop_reason, stop_code contains the 32-bit code reported by the guest kernel. Unikraft Cloud also uses platform-defined values when the stop originates in the platform before the guest kernel can report its own code.

Currently the platform-defined values are:

When the guest kernel reports a stop code, it uses the following encoding:

Reason

The reason can be any of the following values:

A reason of 0 indicates a clean shutdown. Ignore the other bits of stop_code when checking for a crash.

Init level

initlvl indicates the initialization or shutdown phase at stop time. A level of 127 means the instance was executing the app.

Shutdown bit

shutdown_bit indicates the system was shutting down.

Error number

errno is a Linux error code number that provides more detail about the root cause.

By default, a guest that runs out of memory stops the whole instance instead of killing a single process. The workload then doesn't continue in a partial state. A process can opt in to the out-of-memory killer by setting its /proc/self/oom_score_adj to 0. The kernel may then kill that process alone and keep the instance running, so the rest of the workload has to cope with losing it.

Restart policy

When an instance stops because the app exits or crashes, Unikraft Cloud can restart it automatically according to the restart policy. The policy can have the following values:

When an instance stops, Unikraft Cloud evaluates the stop reason and the restart policy to decide whether to restart. It uses an exponential back-off delay (immediate, 5s, 10s, 20s, 40s, 5m) to slow down restarts in tight crash loops. If an instance runs without problems for 10s, Unikraft Cloud resets the back-off delay and the restart sequence ends.

The restart.attempt value in GET /instances counts restarts in the current sequence. The number of completed restarts is restart_count. The restart.next_at field indicates when the next restart occurs if a back-off delay is in effect.

A manual start or stop of the instance aborts the restart sequence and resets the back-off delay.

Creating instances

Instance types

Every instance runs as one of two virtual machine types, which you pick with --type:

Full VMs running on QEMU are required for GPU support. They don't support branching, checkpointing, or vertical scaling yet, and work only with block-based volumes rather than virtiofs. A create request therefore can't combine --type=full with --branch or --checkpoint.

Replicas

The POST /instances request accepts a replicas field (default 0) that creates more copies of the instance alongside the base one.

All instances share the same image, memory, arguments, and service group configuration. Replicas receive independent names and UUIDs.

You can do this with the CLI as well:

Code
unikraft instance create --replicas 2 ...

Vertical scaling

An instance can grow and shrink its memory and vCPUs while it runs. Opt in by setting a range in the create request: min_memory_mb and max_memory_mb for memory, min_vcpus and max_vcpus for vCPUs. The instance boots with the minimum, and the platform adjusts the size within the range based on the instance's memory utilization and CPU pressure. See Vertical scaling for the details, requirements, and limitations.

GPUs

Instances can run with an NVIDIA GPU attached. Depending on the host, that GPU is either a whole physical GPU or a vGPU. A vGPU is a virtual GPU that the host carves out of a physical GPU, so more than one instance shares the physical GPU. A vGPU reports the same model as the physical GPU it comes from, and your workload uses it like any other GPU.

Pass --gpus when you create the instance, together with the full instance type that GPUs require:

Code
unikraft instance create --metro fra \
  --name my-inference-app \
  --image my-inference-app:latest \
  --memory 4096 \
  --type full \
  --gpus 1

An instance can currently hold at most one GPU, and you can't choose which one. Build the workload image on a glibc-based distribution rather than Alpine, because the NVIDIA user-space libraries don't run on musl.

GPU allocation

The platform allocates a GPU when the instance starts, not when you create it, and this includes instances created with autostart. On the first start, it picks any free GPU on the host and records that GPU's UUID and model on the instance. If no GPU is free, the start fails with an error stating that no GPU matching the instance is currently available.

The instance holds the GPU only while it runs. Stopping the instance, or scaling it to zero, returns the GPU to the host's pool so another instance can use it in the meantime. On every later start, the platform first tries to reacquire the same GPU, and falls back to any free GPU of the same model if another instance holds that one. It never assigns a GPU of a different model, because a resumed guest expects the same hardware as before the suspend. To reserve GPU capacity for a set of instances, limit how many of them run at the same time.

To see the GPU an instance holds, inspect it:

Code
unikraft instance get my-inference-app

The gpus.*.allocated field reports whether the instance holds a GPU right now. The gpus.*.uuid and gpus.*.model fields identify that GPU. The model is the GPU's vendor and device ID in hexadecimal form, such as 10de:1eb8 for an NVIDIA Tesla T4. A stopped instance holds no GPU, so it reports allocated as false and no UUID, but keeps the model it last ran on. resources.gpus reports how many GPUs the instance requests. Listings sort and filter on these fields like any other field.

Scale-to-zero and templates for GPU instances

GPU instances backed by a vGPU support scale-to-zero, suspend and resume, and instance templates. Suspending a GPU instance requires a GPU that can save and restore its device state, which vGPUs support.

When a vGPU instance scales to zero, the platform snapshots the VM together with the state of its GPU, detaches the GPU, and returns it to the pool. On the next request, the platform reacquires a GPU as described in GPU allocation and resumes the VM from the snapshot with the GPU attached. This lets a host serve more GPU instances than it has GPUs. An idle instance releases its GPU, and a woken instance resumes on any free GPU of the same model.

A GPU accesses guest memory directly and can't wait for a page the platform hasn't loaded yet. Resuming a GPU instance loads its whole memory from the snapshot before the VM continues, so resume time grows with the instance's memory size. CPU-only instances load memory on demand instead.

Instances created from a template of a GPU instance inherit its GPU configuration and model. A create request that uses such a template can't set --gpus. The value comes from the template.

Wait for running

By default POST /instances returns as soon as the platform queues the instance. Set timeout_s non-zero to block until the instance reaches the running state or the timeout expires. For example:

POST /instances
{
  ...
  "image": "nginx:latest",
  "memory_mb": 256,
  "autostart": true,
  "timeout_s": 10,
  ...
}

To wait for an existing instance, pass query parameters to the wait endpoint:

Code
unikraft api '/v1/instances/<UUID>/wait?state=running&timeout_s=30'

Delete on stop

Pass delete-on-stop in the features array to automatically delete the instance when it stops:

POST /instances
{
  ...
  "image": "nginx:latest",
  "memory_mb": 256,
  "features": ["delete-on-stop"],
  "restart_policy": "never",
  ...
}

This is useful for ephemeral workloads—batch jobs, one-shot tasks—where you don't need to keep the stopped instance.

You can also use the CLI to set this up:

Code
unikraft instance create --rm ...

Nested virtualization

An instance runs without the host's virtualization extensions by default, since the platform hides them from the guest. Pass nested-virt in the features array to expose them, so that a workload shipping its own virtual machines runs as an ordinary instance:

POST /instances
{
  ...
  "image": "my-workload:latest",
  "memory_mb": 4096,
  "features": ["nested-virt"],
  ...
}

You can also use the CLI to set this up:

Code
unikraft instance create --feature nested-virt ...

The guest kernel needs the matching driver to use the extensions, and exposes /dev/kvm once the driver is active. On x86_64, a Linux guest needs CONFIG_KVM together with CONFIG_KVM_INTEL or CONFIG_KVM_AMD. On arm64, a Linux guest needs CONFIG_KVM, which the kernel builds in rather than loading as a module.

The host must support nested virtualization itself. An instance with nested-virt doesn't start on a host without this support.

Stopping instances

Drain timeout

By default PUT /instances/stop stops the instance immediately. Set drain_timeout_ms to allow the instance to finish serving in-flight connections before it stops.

PUT /instances/stop
{
  ...
  "name": "my-instance",
  "drain_timeout_ms": 5000,
  ...
}

You can also use the CLI to set this up:

Code
unikraft instance stop --drain-timeout 5s my-instance

While draining, the instance enters the draining state. The platform accepts no new connections. The instance stops once all connections close or the timeout elapses.

Instance templates

An instance template is a snapshotted instance that acts as a source for cloning new instances. Cloning a template creates a new instance that resumes from the exact original system state. It preserves memory contents, open files, and populated caches to bypass the standard boot sequence. Once you convert an instance into a template, you can't reverse the process.

To transition an actively running instance into a template, from the guest write the value 1 to /uk/libukp/template_instance:

Convert instance to template
echo 1 > /uk/libukp/template_instance

This action instructs the controller to freeze running processes and save the instance as a reusable template. The write blocks until the platform has snapshotted the instance and created the new instance from the resulting template. When the write returns, the guest is already running as the freshly cloned instance, restored from the snapshot rather than continuing as the original.

This lets the guest finish any instance-specific setup—such as reading per-instance data from an attached inline ROM—immediately after the write completes.

If the template already exists, the clone happens right away and the write returns without re-snapshotting. You can also create a template from an instance (even when it's running) by calling POST /instances/templates, or using the CLI:

Code
unikraft instance template create httpserver-go121-taud8

Code
metro:           fra
name:            httpserver-go121-taud8
uuid:            bd281cc4-7640-4cbc-af48-5a44c2bd7b74
state:           template
image:           <my-org>/httpserver-go121
resources:
  memory:        256MiB
  vcpus:         1
timestamps:
  created:       6 days ago
scale-to-zero:
  enabled:       true
  policy:        on
  cooldown-time: 1s

You can list templates with GET /instances/templates or the CLI:

Code
unikraft instance template list

Code
METRO  NAME                    STATE     IMAGE                      ARGS  MEMORY  VCPUS  CREATED
fra    httpserver-go121-taud8  template  <my-org>/httpserver-go121        256MiB  1      6 days ago

Now, you can create an instance from the template using the unikraft CLI:

Code
unikraft instance create --metro fra \
  --template httpserver-go121-taud8 \
  --name httpserver-go121-clone

Code
metro:           fra
name:            httpserver-go121-clone
uuid:            91796fdb-bd41-4c7b-856f-9e60356c96bd
state:           standby
image:           acioc/httpserver-go121
resources:
  memory:        256MiB
  vcpus:         1
networks:
- uuid:          8c778b8b-6ede-4e87-a825-159a2269fd19
  private-ip:    10.0.0.85
  mac:           12:b0:0a:00:00:55
timestamps:
  created:       just now
scale-to-zero:
  enabled:       true
  policy:        on
  cooldown-time: 1s

Templates support delete locks, tags, and autokill. The platform measures autokill on a template from the time of last clone, not from instance stop time.

Updating a template

You can move a template to new images without recreating it. A PATCH /instances/templates request changes the image of a template, and the images of its ROMs and plugins:

Code
unikraft api /v1/instances/templates -X PATCH --metro fra \
  '[
    { "name": "web-base", "prop": "image", "op": "set", "value": "<my-org>/web:v2" }
  ]'

These properties only take the set operation. The patches for one template in a request make up a single update, and if one of them fails, none of them applies.

The platform boots a new revision of the template with the new images, and turns it into a template the same way as the first revision. Once the new revision is ready, it takes over the UUID and the name of the template. While the update runs, the status of the template lists it in updates as pending. If the new revision fails, the template doesn't change, and updates reports the update as failed, with the reason in error.

The instances of the template then follow the update:

• An instance created from the template uses the new revision at its next start, unless it has a snapshot of its own. This includes instances that scale to zero in stateless mode.
• An instance with a snapshot of its own, for example a suspended one, keeps its revision as long as it has that snapshot.
• Templates created from the updated template follow it, and autoscale uses the new revision for new instances.
• An instance with an image of its own, or with ROMs or plugins that replace those of the template, keeps its revision. That holds whether you set them at creation or later.

The status of an instance created from a template names its source in clone_source.

Note the following:

• You can't update a template with volumes, or a template without exactly one network interface.
• A template takes one update at a time. A request for a template whose update still runs fails.
• An update of the ROMs or plugins must list every ROM or plugin of the template, except those inherited from a parent template, with the same names, paths, and authorization. Only their images and the plugin configuration change.
• A template created from another template changes its image only together with its parent.

Nested templates

You can clone a template from another template, creating a hierarchy. Each clone inherits the parent's full state at clone time and can independently accumulate further state before you convert it into its own template. This enables layered configurations, for example a base template with a warm database connection pool, and child templates specialized for different query workloads.

No depth limit applies to nesting, and circular references aren't possible because the template state is immutable once set.

For more information, check out the API reference for instance templates here.

Instance metrics

Use the GET /instances/metrics endpoint to retrieve runtime statistics for one or more instances. With no identifiers, the platform returns metrics for all instances in your account. For more information, check out this dedicated section on instance metrics.

Instance logs

Use the GET /instances/logs endpoint to retrieve logs for one or more instances. The logs capture the instance's stdout and stderr output, and they're preserved across restarts and stops.

Read endpoints accept query parameters as an alternative to a JSON body. For example, to read the last 4 KiB of an instance's log:

Code
unikraft api '/v1/instances/<UUID>/log?offset=-4096&limit=4096'

A request that sends a body can't also give query parameters, including uuid or name.

With the CLI, you can also follow the logs in real time:

Code
unikraft instance logs --follow my-instance

Learn more

• The CLI reference.
• Unikraft Cloud's REST API reference, in particular the section on instances.