Hypeman

Run containerized workloads in VMs, powered by Cloud Hypervisor.

Getting Started

Prerequisites

Go 1.25.4+, KVM, erofs-utils

mkfs.erofs --version

KVM Access: User must be in kvm group for VM access:

sudo usermod -aG kvm $USER
# Log out and back in, or use: newgrp kvm

Configuration

Environment variables

cp .env.example .env
# Edit .env and set JWT_SECRET

Data directory

Hypeman stores data in a configurable directory. Configure permissions for this directory.

sudo mkdir /var/lib/hypeman
sudo chown $USER:$USER /var/lib/hypeman

Dockerhub login

Requires Docker Hub authentication to avoid rate limits when running the tests:

docker login

Docker itself isn't required to be installed. ~/.docker/config.json is a standard used for handling registry authentication.

Build

make build

Running the Server

1. Copy the example environment file and modify the values:

cp .env.example .env
# Edit .env and set JWT_SECRET and other configuration values

2. Generate a JWT token for testing (optional):

make gen-jwt

3. Start the server with hot-reload for development:

make dev

The server will start on port 8080 (configurable via PORT environment variable).

Testing

make test

Code Generation

After modifying openapi.yaml, regenerate the Go code:

make oapi-generate

After modifying dependency injection in cmd/api/wire.go or lib/providers/providers.go, regenerate wire code:

make generate-wire

Or generate everything at once:

make generate-all