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