> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stratosphere-ve/ozone/llms.txt
> Use this file to discover all available pages before exploring further.

# Ozone: QEMU VM Management Library for Go

> Ozone provides Go packages for managing QEMU virtual machines — start/stop lifecycle, JSON config parsing, and strongly-typed resource accessors for CPU, memory, network, and disk.

Ozone is Stratosphere's open-source Go library for managing QEMU virtual machines. It abstracts the complexity of launching and stopping `qemu-system-x86_64` processes and provides a structured, JSON-driven configuration model so that VM definitions live in version-controllable files rather than ad-hoc shell scripts. Whether you are building an internal cloud platform or automating local development environments, Ozone gives you a clean Go API to describe, start, and stop virtual machines without writing raw QEMU command lines by hand.

## Packages

Ozone is organised into two focused packages that can be used independently or together.

**`qemu`** — Lifecycle management. Contains `Start()` and `Stop()` functions. `Start()` prompts for a VM name via stdin, calls `vmparser.VMParser` to load the config, and launches `qemu-system-x86_64` with the `q35` machine type and a QMP control socket on `tcp:127.0.0.1:4444`. `Stop()` runs a `system_powerdown` command to halt the guest.

**`vmparser`** — Configuration parsing and writing. Reads and writes JSON VM definition files stored under a `vms/` directory. Exposes both whole-VM accessors (`VMParser`, `GetVM`) and fine-grained, strongly-typed accessors for each resource group: CPU, memory, network, and disk.

## Explore Ozone

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install Ozone, write your first VM config, and boot a virtual machine in minutes.
  </Card>

  <Card title="VM Configuration" icon="file-code" href="/vm-config/overview">
    Learn the full JSON schema for defining CPU, memory, network, and disk resources.
  </Card>

  <Card title="QEMU Management" icon="server" href="/qemu/start">
    Understand how `qemu.Start()` and `qemu.Stop()` control the VM lifecycle.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/vmparser">
    Browse every exported function and type in the `qemu` and `vmparser` packages.
  </Card>
</CardGroup>

## Key Features

* **q35 machine type** — VMs are launched with `-machine q35`, providing a modern PCIe-based chipset suitable for most guest operating systems.
* **QMP over TCP** — Ozone opens a QEMU Machine Protocol socket at `tcp:127.0.0.1:4444` (`server,nowait`), enabling programmatic VM control without attaching to a console.
* **JSON VM definitions** — Each VM is described by a single JSON file under the `vms/` directory (e.g. `vms/myvm.json`), keeping configuration declarative and diff-friendly.
* **Strongly-typed accessors** — The `vmparser` package exposes individual getter functions (`GetCPUCores`, `GetMemorySizeMB`, `GetMAC`, `GetDiskPath`, …) so callers never have to navigate raw `map[string]interface{}` values.
* **Selective config writers** — Per-resource writer functions (`VMParserWriterCPU`, `VMParserWriterMemory`, `VMParserWriterNetwork`, `VMParserWriterDisk`, `VMParserWriterInfo`) update only the relevant section of a config file while preserving all other fields.
* **Zero external dependencies** — The `go.mod` declares only the Go standard library, making Ozone straightforward to vendor or embed.

## How It Works

The diagram below shows the relationship between a VM config file, the `vmparser` package, and `qemu.Start()`.

```
vms/myvm.json
      │
      │  vmparser.VMParser("myvm")
      ▼
  vmparser.VM  ──────────────────► qemu.Start()
  (CPU / Memory / Network / Disk)       │
                                        │  exec.Command(
                                        │    "qemu-system-x86_64",
                                        │    "-machine", "q35",
                                        │    "-smp", "4",
                                        │    "-qmp", "tcp:127.0.0.1:4444,server,nowait",
                                        │    ...
                                        │  )
                                        ▼
                                  Running QEMU VM
```

`Start()` reads the VM name interactively from stdin, calls `vmparser.VMParser` to load the config from `vms/<vmname>.json`, and then launches the QEMU process via `exec.Command`. `Stop()` runs `system_powerdown` to halt the guest.

<Note>
  `qemu.Start()` reads the VM name from standard input using `fmt.Scanln`, making it interactive by design. See the [Quickstart](/quickstart) for a full walkthrough, and the [API Reference](/api-reference/vmparser) if you need to call `vmparser.VMParser` directly for non-interactive or programmatic use.
</Note>