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

# Get Started with Ozone in Go

> Learn how to install Ozone, define your first VM configuration file, and start a QEMU virtual machine in a few steps.

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.

<Steps>
  <Step title="Prerequisites">
    Before you begin, make sure the following tools are installed on your system:

    * **Go 1.21 or later** — [Download Go](https://go.dev/dl/)
    * **`qemu-system-x86_64`** — Install via your system's package manager, for example:

    ```bash theme={null}
    # 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.
  </Step>

  <Step title="Install Ozone">
    Add Ozone to your Go module:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    mkdir -p vms
    ```

    ```json theme={null}
    {
      "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`.

    <Tip>
      See the [VM Configuration](/vm-config/overview) page for a full description of every field, including all supported CPU types, network modes, and disk formats.
    </Tip>
  </Step>

  <Step title="Parse the VM config">
    Use `vmparser.VMParser` to load the full VM definition into a strongly-typed `*vmparser.VM` struct:

    ```go theme={null}
    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.
  </Step>

  <Step title="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:

    ```go theme={null}
    package main

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

    func main() {
        qemu.Start()
    }
    ```

    Run your program:

    ```bash theme={null}
    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.

    <Note>
      `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.
    </Note>
  </Step>
</Steps>

## Next Steps

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

* **[VM Configuration](/vm-config/overview)** — 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](/qemu/start)** — Understand how `qemu.Stop()` runs `system_powerdown` and how Ozone exposes a QMP socket for communicating with a running VM.
* **[API Reference](/api-reference/vmparser)** — Full reference for all exported functions and types in the `qemu` and `vmparser` packages.