What is unikraft skill used for?

It guides using the kraft CLI to build and deploy Unikraft unikernels, manage libraries, packages, networking, volumes, and compose workflows.

Do I need UKC_TOKEN and UKC_METRO for cloud operations?

Yes. UKC_TOKEN authenticates to Unikraft Cloud and UKC_METRO selects the region; both are required for cloud interactions.

How can I preview commands before execution?

The skill emphasizes showing commands in copy-paste friendly code blocks before execution and asks for confirmation if needed.

unikraft

npx machina-cli add skill guillempuche/ai-standards/unikraft --openclaw

Files (1)

SKILL.md

18.0 KB

Kraft CLI Reference

Build and deploy unikernels with the kraft CLI.

Documentation: https://unikraft.org/docs/cli
Issues & support: https://github.com/unikraft/kraftkit/issues
Platform: https://unikraft.cloud

Important: Running Kraft Commands

When working with kraft CLI commands:

Always show the commands first - Tell the developer what commands to run before executing them
Format for copy-paste - Display commands in a code block ready to copy-paste into the terminal
Ask before running - Ask if the developer wants you to run the commands, as there can be authentication issues when UKC_TOKEN is not set in the AI's terminal session
Let developer run if needed - If commands fail due to missing tokens, provide the commands for the developer to run manually

Environment Setup

Required for cloud commands (developer must set these in their terminal):

export UKC_TOKEN="your-token"   # Unikraft Cloud API token
export UKC_METRO=fra            # Metro/region (e.g., fra, ams, lon)

Build Commands

kraft build                 # Configure and build Unikraft unikernels
kraft clean                 # Remove build object files
kraft menu                  # Open configuration editor TUI

Project Library Commands

kraft lib add <lib>         # Add unikraft library to the project
kraft lib create            # Initialize a library from a template
kraft lib remove <lib>      # Remove a library dependency

Packaging Commands

kraft pkg list              # List installed Unikraft component packages
kraft pkg pull <pkg>        # Pull a unikernel and/or its dependencies
kraft pkg push              # Push a unikernel package to registry
kraft pkg update            # Retrieve new component/library/package lists
kraft pkg info <pkg>        # Show information about a package
kraft pkg export            # Export a package
kraft pkg remove            # Remove selected local packages

Local Runtime Commands

kraft run                   # Run a unikernel
kraft ps                    # List running unikernels
kraft stop <name>           # Stop one or more running unikernels
kraft start <name>          # Start one or more machines
kraft pause <name>          # Pause one or more running unikernels
kraft logs <name>           # Fetch the logs of a unikernel
kraft remove <name>         # Remove one or more running unikernels

Local Networking Commands

kraft net create            # Create a new machine network
kraft net list              # List machine networks
kraft net inspect <name>    # Inspect a machine network
kraft net up <name>         # Bring a network online
kraft net down <name>       # Bring a network offline
kraft net remove <name>     # Remove a network

Local Volume Commands

kraft vol create            # Create a machine volume
kraft vol ls                # List machine volumes
kraft vol inspect <name>    # Inspect a machine volume
kraft vol remove <name>     # Remove a volume

Compose Commands (Local)

kraft compose up            # Run a compose project
kraft compose down          # Stop and remove a compose project
kraft compose ps            # List running services of current project
kraft compose logs          # Print the logs of services
kraft compose build         # Build or rebuild services
kraft compose create        # Create a compose project
kraft compose start         # Start a compose project
kraft compose stop          # Stop a compose project
kraft compose pause         # Pause a compose project
kraft compose unpause       # Unpause a compose project
kraft compose pull          # Pull images of services
kraft compose push          # Push images of services

Cloud Deployment Commands

kraft cloud deploy          # Deploy your application to Unikraft Cloud
kraft cloud quota           # View your resource quota
kraft cloud tunnel          # Forward a local port to an unexposed instance

Cloud Instance Commands

kraft cloud instance create   # Create an instance
kraft cloud instance list     # List instances
kraft cloud instance get      # Retrieve the state of instances
kraft cloud instance logs     # Get console output of instances
kraft cloud instance start    # Start instances
kraft cloud instance stop     # Stop instances
kraft cloud instance restart  # Restart instance(s)
kraft cloud instance remove   # Remove instances

Cloud Service Commands

kraft cloud service create  # Create a service
kraft cloud service list    # List services
kraft cloud service get     # Retrieve the state of services
kraft cloud service logs    # Get console output for services
kraft cloud service drain   # Drain instances in a service
kraft cloud service remove  # Delete services

Cloud Image Commands

kraft cloud image list      # List all images at a metro for your account
kraft cloud image remove    # Remove an image

Cloud Volume Commands

kraft cloud volume create   # Create a persistent volume
kraft cloud volume list     # List persistent volumes
kraft cloud volume get      # Retrieve the state of persistent volumes
kraft cloud volume import   # Import local data to a persistent volume
kraft cloud volume attach   # Attach a persistent volume to an instance
kraft cloud volume detach   # Detach a persistent volume from an instance
kraft cloud volume remove   # Permanently delete persistent volume(s)

Cloud Volume Template Commands

kraft cloud volume template create  # Create volume template(s)
kraft cloud volume template list    # List volume templates
kraft cloud volume template get     # Retrieve the state of volume templates
kraft cloud volume template remove  # Permanently delete volume template(s)

Cloud Autoscale Commands

kraft cloud scale init      # Initialize autoscale configuration for a service
kraft cloud scale add       # Add an autoscale configuration policy
kraft cloud scale get       # Get an autoscale configuration or policy
kraft cloud scale remove    # Delete an autoscale configuration policy
kraft cloud scale reset     # Reset autoscale configuration of a service

Cloud Certificate Commands

kraft cloud cert create     # Create a certificate
kraft cloud cert list       # List certificates
kraft cloud cert get        # Retrieve the status of a certificate
kraft cloud cert remove     # Remove a certificate

Cloud Compose Commands

kraft cloud compose up      # Deploy services in a compose project to Unikraft Cloud
kraft cloud compose down    # Stop and remove services in a deployment
kraft cloud compose ps      # List active services of a Compose project
kraft cloud compose log     # View logs of services in a deployment
kraft cloud compose build   # Build a compose project
kraft cloud compose create  # Create a deployment from a Compose project
kraft cloud compose start   # Start services in a deployment
kraft cloud compose stop    # Stop services in a deployment
kraft cloud compose push    # Push images to Unikraft Cloud from a Compose project
kraft cloud compose ls      # List service deployments at a given path

Useful Flags

--no-prompt                 # Do not prompt for user interaction
--no-color                  # Disable color output
--log-level <level>         # Log level: panic, fatal, error, warn, info, debug, trace
--help                      # Help for any command

Xiroi Server Deployment

Project Structure

Both Kraftfile and Dockerfile.server MUST be at repository root:

/xiroi (repo root)
├── Kraftfile              # Unikraft config (rootfs: ./Dockerfile.server)
├── Dockerfile.server      # FROM scratch optimized image
└── xiroi-apps/server/
    ├── Dockerfile.local       # Alpine-based for local debugging
    └── run_server_docker.sh   # Local Docker testing script

Why at root? Kraft CLI doesn't support parent directory references (../) in rootfs path, and Docker needs repo root as build context to COPY xiroi-apps/, xiroi-packages/, etc.

Kraftfile Configuration

spec: v0.6
name: xiroi-server
runtime: base-compat:latest

labels:
  cloud.unikraft.v1.instances/scale_to_zero.policy: "on"
  cloud.unikraft.v1.instances/scale_to_zero.stateful: "false"
  cloud.unikraft.v1.instances/scale_to_zero.cooldown_time_ms: 1000

rootfs: ./Dockerfile.server

cmd: ["/usr/bin/node", "/app/dist/index.js"]

Dockerfile.server Key Features

The production Dockerfile uses FROM scratch for minimal Unikraft compatibility:

Multi-stage build - Builder stage uses node:24-alpine
FROM scratch runtime - Copies only required binaries/libraries
Manual library copying - Must copy ld-musl, libgcc_s, libstdc++
SSL certificates - Required for HTTPS connections (Neon DB, etc.)
Empty .env files - Dotenv needs files to exist even if env vars come from -e flags

Deploy Commands

Manual deployment:

source .env.github
export UKC_TOKEN="$KRAFTCLOUD_TOKEN"

kraft cloud --metro fra deploy \
  --name xiroi-server-prod \
  -M 1024 \
  -p 443:4000 \
  --scale-to-zero off \
  -e NODE_ENV=production \
  -e SERVER_PORT=4000 \
  -e ALLOWED_ORIGINS="${ALLOWED_ORIGINS}" \
  # ... other env vars
  .

Delete and redeploy (if instance exists):

kraft cloud --metro fra instance delete xiroi-server-prod
# Then run deploy command again

Rolling Updates (Zero-Downtime)

After the first deployment, KraftCloud creates a Service (load balancer) that owns the domain and port. Subsequent deployments can use rolling updates for zero downtime.

Architecture:

Service (load balancer)
  └── Instance (old) ──┐
  └── Instance (new) ──┘  ← Rolling update adds new, then removes old

Key constraints for rolling updates:

--service <name> is mutually exclusive with -p and -d (service already owns these)
--name must be omitted (kraft auto-generates unique names so new instance can spin up while old exists)

Rolling update command:

kraft cloud --metro fra deploy \
  --service <service-name> \
  --rollout remove_sequential \
  --rollout-wait 30s \
  -M 1024 \
  --scale-to-zero off \
  -e NODE_ENV=production \
  # ... other env vars
  .

Get service name after first deployment:

kraft cloud --metro fra service list
# Look for FQDN matching your domain (e.g., api.xiroi.cat)

Rollout strategies:

Strategy	Behavior
`remove_sequential`	Start new → wait → remove old (zero downtime)
`remove`	Remove old immediately after new starts
`stop`	Stop old (don't remove) after new starts
`keep`	Keep old running alongside new
`abort`	Cancel if old exists

Critical Flags

Flag	Value	Purpose
`--metro`	`fra`	Frankfurt region
`-M`	`1024`	Memory in MiB
`-p`	`443:4000`	HTTPS → app port
`--scale-to-zero`	`off`	Keep always running (avoids wake-up issues)

Scale-to-Zero Considerations

Why --scale-to-zero off?

Node.js server has slow cold starts (267ms+)
Database connections need to stay alive
Wake-up mechanism can cause 504 timeouts

If you want scale-to-zero later:

--scale-to-zero on --scale-to-zero-cooldown 300000ms  # 5 min cooldown

Troubleshooting

Error	Cause	Fix
`ErrorDotenv`	`process.cwd()` returns `/` on scratch	Use `/app` as base dir in production
`instance already exists`	Previous deployment	Delete first: `kraft cloud instance delete <name>`
`instance already exists` (rolling update)	`--name` specified with `--rollout`	Omit `--name` flag for rolling updates
`cannot use --service and --port`	Flags are mutually exclusive	Use `--service` without `-p` or `-d`
`504 Gateway Timeout`	Scale-to-zero wake-up failing	Use `--scale-to-zero off`
`could not build initrd from: ../..`	Relative path in rootfs	Keep Kraftfile at repo root

Verify Deployment

# List instances
kraft cloud --metro fra instance list | grep xiroi

# Check health
curl -s https://<your-domain>.fra.unikraft.app/api/health
# Returns: {"message":"OK"}

# View logs
kraft cloud --metro fra instance logs xiroi-server-prod

Examples Repository

Reference examples: https://github.com/unikraft-cloud/examples

All Example Folders

bun                              # Bun JavaScript runtime
caddy2.7-go1.21                  # Caddy web server with Go
code-server                      # Browser-based VS Code
database-redis7.2                # Redis in-memory store
debian-ssh                       # SSH access environment
dragonflydb                      # Modern Redis alternative
duckdb-go1.21                    # DuckDB analytical database with Go
expressjs4.18-node21             # Express.js framework
flask-redis                      # Flask with Redis
flask3.0-python3.12-sqlite3      # Flask with SQLite
grafana                          # Monitoring and visualization
haproxy                          # High availability proxy
http-c-debug                     # C HTTP server (debug)
http-elixir1.17                  # Elixir HTTP server
http-java21                      # Java 21 HTTP server
http-node25                      # Node.js 25 HTTP server
http-perl5.42                    # Perl HTTP server
http-python3.12-FastAPI-0.121.3  # FastAPI framework
http-rust-1.79-axum-scale-to-zero # Rust Axum with autoscaling
http-rust-trunkrs-leptos         # Rust Leptos full-stack
http-rust1.91                    # Rust HTTP server
httpserver-boost1.74-g++13.2     # C++ with Boost
httpserver-dotnet10.0            # .NET 10.0
httpserver-dotnet8.0             # .NET 8.0
httpserver-elixir1.16            # Elixir 1.16
httpserver-erlang26.2            # Erlang 26.2
httpserver-g++13.2               # C++ with GCC
httpserver-gcc13.2               # C with GCC
httpserver-go1.21                # Go 1.21
httpserver-go1.22-redis          # Go with Redis
httpserver-java17                # Java 17
httpserver-lua5.1                # Lua 5.1
httpserver-nodejs21              # Node.js 21
httpserver-perl5.38              # Perl 5.38
httpserver-php8.2                # PHP 8.2
httpserver-python3.12            # Python 3.12
httpserver-python3.12-django5.0  # Django 5.0
httpserver-python3.12-flask3.0   # Flask 3.0
httpserver-ruby3.2               # Ruby 3.2
httpserver-rust1.73              # Rust 1.73
httpserver-rust1.75              # Rust 1.75
httpserver-rust1.81-rocket0.5    # Rust Rocket framework
httpserver-rust1.87-actix-web4   # Rust Actix-web
hugo0.122                        # Hugo static site generator
imaginary                        # Image processing service
java17-spring-petclinic          # Spring Framework sample
java17-springboot3.2.x           # Spring Boot
mariadb                          # MariaDB database
mariadb11.7-volumes              # MariaDB with volumes
mcp-server-arxiv                 # MCP for arXiv
mcp-server-simple                # Basic MCP server
memcached1.6                     # Memcached
minio                            # S3-compatible storage
mongodb                          # MongoDB database
nginx                            # Nginx web server
nginx-flask-mongo                # Nginx + Flask + MongoDB
nginx-vite-vanilla               # Nginx with Vite
node-express-puppeteer           # Express with Puppeteer
node-playwright-chromium         # Playwright (Chromium)
node-playwright-firefox          # Playwright (Firefox)
node-playwright-webkit           # Playwright (WebKit)
node-vite-ssr-vanilla            # Vite SSR
node-vite-vanilla                # Vite vanilla
node18-agario                    # Agar.io game
node18-wingsio                   # Wings.io game
node21-nextjs                    # Next.js framework
node21-remix                     # Remix framework
node21-solid-start               # SolidJS framework
node21-sveltekit                 # SvelteKit framework
node21-websocket                 # WebSocket example
node24-karaoke                   # Karaoke application
opentelemetry-collector          # OpenTelemetry
postgres                         # PostgreSQL database
prisma-expressjs4.19-node18      # Prisma ORM with Express
python-playwright-chromium       # Python Playwright
python3.12-flask3.0-sqlite       # Flask with SQLite
ruby3.2-rails                    # Ruby on Rails
skipper0.18                      # HTTP router
spin-wagi-http                   # WebAssembly Gateway Interface
traefik                          # Traefik proxy
tyk                              # API gateway
vnc-browser                      # Browser-based VNC
vsftpd                           # FTP server
wazero-import-go                 # WebAssembly for Go
webhook-github-node              # GitHub webhook handler
wordpress-all-in-one             # WordPress single deploy
wordpress-compose                # WordPress with Compose

Source

git clone https://github.com/guillempuche/ai-standards/blob/main/skills/unikraft/SKILL.mdView on GitHub

Overview

This skill teaches you to use the kraft CLI to build, package, and deploy Unikraft unikernels. It covers project setup, library and package management, local runtime control, networking, volumes, and compose workflows, including cloud deployment with Unikraft Cloud tokens. Mastery enables reproducible Unikraft deployments across local and cloud environments.

How This Skill Works

The kraft CLI groups actions into build, lib, pkg, runtime, net, vol, and compose categories. You configure a Kraftfile-based project, set cloud credentials (UKC_TOKEN) and region (UKC_METRO), and then run commands shown in code blocks before execution. The CLI reports status, logs, and results to guide from local builds to cloud deployments.

When to Use It

Starting a new Unikraft project and configuring libraries with kraft lib, then building with kraft build.
Managing dependencies and packaging, including pulling and exporting packages for registries or cloud deployment.
Running, monitoring, and debugging unikernels locally with kraft run, kraft ps, and kraft logs.
Creating and managing local networks, volumes, and multi-service stacks with kraft net, kraft vol, and kraft compose.
Deploying to Unikraft Cloud requires UKC_TOKEN and UKC_METRO, using kraft commands to interact with cloud resources.

Quick Start

Step 1: Set up environment variables: export UKC_TOKEN="your-token" and export UKC_METRO=fra
Step 2: Initialize and build: kraft lib create; kraft build; (add libs as needed using kraft lib add <lib>)
Step 3: Run locally or deploy: kraft run to test locally, or kraft pkg push to publish to cloud

Best Practices

Always display the commands in a copy-paste friendly code block before executing them.
Set and protect UKC_TOKEN and UKC_METRO in your terminal session before cloud operations.
Favor library and package management with kraft lib and kraft pkg before building to ensure reproducible builds.
Test locally with kraft run and inspect logs prior to cloud deployment.
Use kraft compose for reproducible multi-service unikernel configurations and version control.

Example Use Cases

Build and run a unikernel locally using kraft build followed by kraft run to verify behavior.
Add a library with kraft lib add, then kraft build to incorporate new dependencies.
Pull a package with kraft pkg pull, inspect with kraft pkg info, and export with kraft pkg export.
Create a local network with kraft net create, list with kraft net list, and inspect with kraft net inspect.
Deploy a unikernel to Unikraft Cloud by authenticating with UKC_TOKEN and pushing via kraft pkg push.

Frequently Asked Questions

Add this skill to your agents