Get Started with Ozone in Go

In this guide you will install the Ozone library, create a JSON VM configuration file, parse it with the vmparser package, and boot your first QEMU virtual machine using qemu.Start() — all from a single Go program.

Prerequisites

Before you begin, make sure the following tools are installed on your system:

Go 1.21 or later — Download Go
qemu-system-x86_64 — Install via your system’s package manager, for example:

# Debian / Ubuntu
sudo apt install qemu-system-x86

# Fedora / RHEL
sudo dnf install qemu-system-x86

# macOS (Homebrew)
brew install qemu

The Ozone module path is github.com/stratosphere-ve/ozone. Your own module must be initialised with go mod init before adding Ozone as a dependency.

Install Ozone

Add Ozone to your Go module:

go get github.com/stratosphere-ve/ozone

This fetches both the qemu and vmparser packages and records the dependency in your go.mod and go.sum files.

Create a VM config file

Ozone reads VM definitions from JSON files stored in a vms/ directory relative to your working directory. Create the directory and add a config file for your first VM:

mkdir -p vms

{
  "vm": {
    "name": "myvm",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "cpu": {
    "cores": 4,
    "type": "host"
  },
  "memory": {
    "size_mb": 2048
  },
  "network": {
    "interface": "virtio",
    "type": "user",
    "mac": "52:54:00:12:34:56"
  },
  "disk": {
    "name": "myvm",
    "path": "myvm.qcow2",
    "size_gb": 20,
    "format": "qcow2"
  }
}

Save this file as vms/myvm.json. The file name without the .json extension is the VM name you will pass to vmparser.VMParser.

See the VM Configuration page for a full description of every field, including all supported CPU types, network modes, and disk formats.

Parse the VM config

Use vmparser.VMParser to load the full VM definition into a strongly-typed *vmparser.VM struct:

package main

import (
    "fmt"
    "log"

    "github.com/stratosphere-ve/ozone/vmparser"
)

func main() {
    vm, err := vmparser.VMParser("myvm")
    if err != nil {
        log.Fatalf("failed to parse VM config: %v", err)
    }

    fmt.Printf("VM name:    %s\n", vm.VM.Name)
    fmt.Printf("CPU cores:  %d\n", vm.CPU.Cores)
    fmt.Printf("Memory:     %d MB\n", vm.Memory.SizeMB)
    fmt.Printf("Disk path:  %s\n", vm.Disk.Path)
    fmt.Printf("MAC:        %s\n", vm.Network.MAC)
}

VMParser constructs the file path as vms/<vmname>.json and unmarshals the JSON into the VM struct, which contains nested VMInfo, CPU, Memory, Network, and Disk fields.

Start the VM

Call qemu.Start() to boot the virtual machine. The function prompts you for the VM name via stdin, parses its config with vmparser.VMParser, and launches qemu-system-x86_64 with the q35 machine type, four vCPUs (-smp 4), and a QMP socket on port 4444:

package main

import (
    "github.com/stratosphere-ve/ozone/qemu"
)

func main() {
    qemu.Start()
}

Run your program:

go run main.go

You will see the prompt:

What VM would you like to start?

Type your VM name (e.g. myvm) and press Enter. Ozone will parse vms/myvm.json, print the resolved VM struct, and execute the QEMU process.

qemu.Start() reads the VM name interactively from standard input using fmt.Scanln. If you need non-interactive or programmatic startup, call vmparser.VMParser directly with your VM name and construct the exec.Command yourself based on the returned config.

Next Steps

Now that your first VM is running, explore the rest of the Ozone documentation:

VM Configuration — Learn every field in the VM JSON schema and how the per-resource writer functions (VMParserWriterCPU, VMParserWriterMemory, etc.) let you update config files in place.
QEMU Management — Understand how qemu.Stop() runs system_powerdown and how Ozone exposes a QMP socket for communicating with a running VM.
API Reference — Full reference for all exported functions and types in the qemu and vmparser packages.

Get Started

VM Configuration

QEMU Management

API Reference

Documentation Index

​Next Steps

Build docs developers (and LLMs) love

Next Steps