Unikraft CLI

Note

This is the new Unikraft CLI. It is actively worked upon to deliver the latest Unikraft Cloud features to your CLI. Feedback appreciated!

The official command-line interface for Unikraft Cloud — deploy and manage unikernels globally in milliseconds.

Development

See CONTRIBUTING.md for build instructions, testing, and release process.

Features

• Deploy Instantly — Run unikernel images as serverless instances with unikraft run
• Global Infrastructure — Deploy across multiple metros with automatic multi-region support
• Resource Management — Full CRUD operations for instances, volumes, services, certificates, and images
• Scale-to-Zero — Built-in support for scale-to-zero policies to optimize costs
• Multiple Output Formats — Machine-readable JSON or human-friendly text output
• Profile Management — Switch between multiple accounts and configurations
• Shell Completions — Tab completion for Bash, Zsh, Fish, and PowerShell

Installation

1-liner (macOS & Linux)

curl --proto '=https' --tlsv1.2 -fsSL https://unikraft.com/cli/install.sh | sh

Installs into the first preferred bin directory found in your PATH (falling back to $HOME/.local/bin if none are available). Use environment variable UNIKRAFT_CLI_INSTALL_BIN_DIR to customize the installation directory.

1-liner (Windows PowerShell)

irm https://unikraft.com/cli/install.ps1 | iex

Installs unikraft.exe into %LOCALAPPDATA%\Programs\Unikraft\bin and adds it to your user PATH. From cmd.exe, run powershell -c "irm https://unikraft.com/cli/install.ps1 | iex" instead. Use environment variable UNIKRAFT_CLI_INSTALL_BIN_DIR to customize the installation directory, or download the windows zip archive from the releases page.

Homebrew (macOS & Linux)

brew install unikraft/cli/unikraft

Debian/Ubuntu

# Update and install dependencies
sudo apt update
sudo apt install ca-certificates curl

# Download and add the GPG key
sudo install -d -m 0755 /etc/apt/keyrings

sudo curl -fsSL \
  -o /etc/apt/keyrings/unikraft-cli.gpg \
  https://pkg.unikraft.com/debian/cli-apt/keys/cli-apt.gpg

sudo tee /etc/apt/sources.list.d/unikraft-cli.sources <<EOF
Types: deb
URIs: https://pkg.unikraft.com/debian/cli-apt/
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Signed-By: /etc/apt/keyrings/unikraft-cli.gpg
EOF

# Update and install the CLI
sudo apt update
sudo apt install unikraft-cli

Fedora/RHEL/Rocky/Alma

# Add the Unikraft CLI repository
sudo tee /etc/yum.repos.d/unikraft-cli-rpm.repo <<EOF
[unikraft]
name=unikraft
baseurl=https://pkg.unikraft.com/rpm/cli-rpm/
gpgcheck=0
enabled=1
EOF

# Install the CLI at the specific pre-release version
yum install unikraft-cli

Nix (flake)

The CLI is packaged in the Unikraft NUR (Nix User Repository), so there are no release hashes to vendor by hand — each release is published there automatically. Supported systems: x86_64-linux, aarch64-linux, x86_64-darwin, and aarch64-darwin.

The repository is consumed directly as a flake input or overlay, as shown below. It is not registered in the nix-community NUR index, so nur.repos.unikraft.* does not resolve.

Run it once without installing:

nix run github:unikraft/nur#unikraft-cli -- version

Install it into your user profile (upgrade later with nix profile upgrade unikraft-cli):

nix profile add github:unikraft/nur#unikraft-cli

On Nix older than 2.30 the subcommand is nix profile install, which newer versions still accept as a deprecated alias for add.

Add it to a flake dev shell as an input:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    unikraft-nur.url = "github:unikraft/nur";
    # Optional: reuse the nixpkgs above instead of evaluating a second one.
    unikraft-nur.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, flake-utils, unikraft-nur }:
    flake-utils.lib.eachDefaultSystem (system:
      let pkgs = import nixpkgs { inherit system; };
      in {
        devShells.default = pkgs.mkShell {
          packages = [ unikraft-nur.packages.${system}.unikraft-cli ];
        };
      });
}

Or apply the overlay to expose the packages on pkgs directly — replace the let ... in body of the example above with:

let
  pkgs = import nixpkgs {
    inherit system;
    overlays = [ unikraft-nur.overlays.default ];
  };
in {
  devShells.default = pkgs.mkShell {
    packages = [ pkgs.unikraft-cli ];
  };
}

The NUR exposes the following package attributes:

Attribute	Description
unikraft-cli	Latest stable release of the Unikraft CLI (recommended)
unikraft-cli-staging	Latest pre-release (-staging) build
kraftkit	Legacy KraftKit, installed as kraft

GitHub Actions

• Requires GitHub Actions.

Use the official unikraft/setup-action to install the CLI in your workflow:

- name: Install Unikraft CLI
  uses: unikraft/setup-action@v1

From Source

• Requires Go;
• Git;
• GNU Make or Task.

# Clone the repository
git clone https://github.com/unikraft-cloud/cli.git
cd cli

# Build the CLI
make cli

# The binary is available in dist/
./dist/unikraft --version

unikraft build dependencies

To use unikraft build to build and publish your own images from Dockerfiles or from regular OCI images, you need a BuildKit builder. The easiest way to get one is via Docker, see https://docs.docker.com/engine/install/ for installation instructions.

Alternatively, you can also directly setup and use BuildKit, see https://github.com/moby/buildkit#quick-start.

Quick Start

1. Login to Unikraft Cloud

unikraft login

This opens your browser for authentication. Alternatively, provide a token file:

unikraft login --token /path/to/token

Or, if you need to directly specify a metro endpoint, you can manually create a profile:

# Linux and macOS: ~/.config/unikraft/config.yaml
# Windows: %AppData%\unikraft\config.yaml
profile: default
profiles:
  default:
    type: cloud
    organization: <org-name>
    token: <api-token>
    metros:
      - name: <metro-name> # e.g. fra
        endpoint: <metro-endpoint> # e.g. https://api.fra.unikraft.cloud
        country: <metro-country> # e.g. de
        insecure: false # skip tls verification (avoid for production use)

You can also use your old, already set, UKC_METRO/UKC_TOKEN by setting also this variable:

export UNIKRAFT_PROFILE_ENV="true"

2. Deploy Your First Instance

unikraft run --metro=fra -p 443:8080/http+tls --image=nginx:latest

This deploys an NGINX instance in Frankfurt with HTTPS enabled.

3. List Your Instances

unikraft instances list

4. View Instance Logs

unikraft instances logs my-instance

Commands

Command	Description
run	Run an image as an instance
build	Build a Unikraft project into a VM image
tui	Browse resources in a TUI
mcp	Serve Unikraft Cloud to AI assistants over the Model Context Protocol
metros	List available metro locations
instances	Manage instances (list, get, create, edit, delete, logs, start, stop, restart)
volumes	Manage persistent volumes (list, get, create, edit, delete, clone)
services	Manage service groups (list, get, create, edit, delete)
certificates	Manage TLS certificates (list, get, create, delete)
images	Manage images (list, get, copy)
login	Login to Unikraft Cloud
logout	Logout from Unikraft Cloud
profile	Manage profiles (list, get, use)
config	Manage CLI configuration
completion	Generate shell completion scripts
version	Show version information
upgrade	Upgrade the Unikraft CLI to the latest version

Examples

Deploy with environment variables:

unikraft run --metro=sfo -e KEY=VALUE -e DEBUG=true --image=my-app:latest

Deploy with an attached volume:

unikraft run --metro=was -v my-volume:/data --image=my-app:latest

Deploy with custom resources:

unikraft run --metro=dal -m 512MiB --vcpus 2 --image=my-app:latest

Deploy with scale-to-zero:

unikraft run --metro=sin --scale-to-zero policy=on,cooldown-time=300 --image=my-app:latest

Create an instance with multiple service ports:

unikraft run --metro=fra -p 443:8080/http+tls -p 80:443/http+redirect --image=nginx:latest

Edit an existing instance:

unikraft instances edit my-instance --set image=nginx:1.27

Clone a volume:

unikraft volumes clone my-volume --set name=my-volume-backup

Build and publish an image from a Kraftfile:

unikraft build . --output my-org/my-app:latest

Configuration

The CLI stores configuration in ~/.config/unikraft/config.yaml on Linux and macOS, and in %AppData%\unikraft\config.yaml on Windows. On Linux and macOS, if XDG_CONFIG_HOME is set, the CLI uses $XDG_CONFIG_HOME/unikraft/config.yaml. If UNIKRAFT_CONFIG is set, the CLI uses that path.

Environment Variables

Variable	Description
UNIKRAFT_CONFIG	Path to the configuration file
UNIKRAFT_PROFILE	Override the current profile
UNIKRAFT_PROFILE_ENV	Use a virtual profile from UKC_* env vars instead of config (true, false)
UNIKRAFT_LOG_LEVEL	Set log level (trace, debug, info, warn, error, fatal)
UNIKRAFT_LOG_TYPE	Set output format (text, json)
UNIKRAFT_TELEMETRY	Enable/disable usage analytics (true, false)
UNIKRAFT_DOCS_URL	Documentation site that unikraft mcp serves as resources; empty serves none
UKC_TOKEN	API token for legacy profiles / UNIKRAFT_PROFILE_ENV
UKC_METRO	Metro name (e.g. fra) or full endpoint URL for legacy profiles / UNIKRAFT_PROFILE_ENV
UKC_ALLOW_INSECURE	Skip TLS verification for the metro from UKC_METRO (true, false)

Profiles

Manage multiple accounts or configurations with profiles:

# List profiles
unikraft profile list

# Switch profile
unikraft profile use staging

# Use a profile for a single command
unikraft --profile=staging instances list

Output Formats

The CLI supports multiple output formats via the -o flag:

# Default table output
unikraft instances list

# JSON output
unikraft instances list -o json

# Show specific fields
unikraft instances get my-instance --fields name,state,image

# Include verbose/detailed fields
unikraft instances get my-instance -v

MCP Server

unikraft mcp lets AI assistants such as Claude Code, Claude Desktop or Cursor manage Unikraft Cloud through the Model Context Protocol. Every resource type gets typed tools such as instance_list or volume_create, instances also get instance_control and instance_logs, and sandboxes get sandbox_exec, sandbox_read and sandbox_write. The tools use the current profile, and the documentation is served as unikraft://docs resources.

Register the server with a client as a stdio server:

{"mcpServers": {"unikraft": {"command": "unikraft", "args": ["mcp"]}}}

With Claude Code:

claude mcp add unikraft -- unikraft mcp

Serve fewer tools to keep the assistant's context small, or only the ones that cannot change anything:

# Only the instance, volume and metro tools
unikraft mcp --resources instance,volume,metro

# Only list, image_get, instance_logs and sandbox_read
unikraft mcp --read-only

Pass --listen to serve over HTTP at /mcp instead, and --tls-cert with --tls-key for HTTPS. Clients then register the server by URL:

unikraft mcp --listen 127.0.0.1:8080

{"mcpServers": {"unikraft": {"type": "http", "url": "http://127.0.0.1:8080/mcp"}}}

Only loopback addresses are accepted unless --allow-remote is given. Every client acts with the profile's credentials, so put an authenticating proxy in front of a server that others can reach.

Shell Completion

Generate completion scripts for your shell:

# Bash
unikraft completion -c bash > /etc/bash_completion.d/unikraft

# Zsh
unikraft completion -c zsh > "${fpath[1]}/_unikraft"

# Fish
unikraft completion -c fish > ~/.config/fish/completions/unikraft.fish

Telemetry

The CLI collects usage analytics to improve the product. When you are logged in, events are keyed to the user and organization UUIDs of the active profile. Otherwise, events use an anonymous machine hash. To opt out:

# Disable for a single command
unikraft --no-telemetry instances list

# Disable permanently
export UNIKRAFT_TELEMETRY=false

# Or
export DO_NOT_TRACK=1

License

BSD-3-Clause. See LICENSE.md for details. Copyright (c) 2026, Unikraft GmbH and The Unikraft CLI Authors.

Links

• Unikraft Cloud Documentation
• Report Issues
• Unikraft Website