---

name: unikraft description: Kraft CLI commands for building and deploying Unikraft unikernels. Use when working with Kraftfiles, deploying to Unikraft Cloud, or managing unikernel instances.

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:

1. Always show the commands first - Tell the developer what commands to run before executing them
2. Format for copy-paste - Display commands in a code block ready to copy-paste into the terminal
3. 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
4. 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):

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

Build Commands

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

Project Library Commands

Copykraft 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

Copykraft 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

Copykraft 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

Copykraft 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

Copykraft 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)

Copykraft 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

Copykraft 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

Copykraft 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

Copykraft 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

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

Cloud Volume Commands

Copykraft 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

Copykraft 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

Copykraft 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

Copykraft 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

Copykraft 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

Copy--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:

Copy/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

Copyspec: 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:

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

Deploy Commands

Manual deployment:

Copysource .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):

Copykraft 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:

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

Key constraints for rolling updates:

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

Rolling update command:

Copykraft 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:

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

Rollout strategies:

Critical Flags

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:

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

Troubleshooting

Verify Deployment

Copy# 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

Copybun                              # 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