vm-spec

name: vm-spec description: | Go type reference for VmSpec and the discriminated-union source types (VmSource cloud_image | bootc | clone | imported | bootstrap). Documents every field, validation rules, and the adopt-user decision. Source files: charly/vm_spec.go, charly/cloud_init_types.go, charly/schema/vm.cue. MUST be invoked before editing VmSpec Go code or authoring vm.yml entries.

vm-spec

Go type reference for the VM surface. VmSpec + VmSource + VmChecksum + VmNetwork + VmSSH + VmKeyInjection + VmCloudInit + VmCharlyInstall are the canonical types that drive charly vm build, charly vm create, and charly bundle add vm:<name>. This skill is the authoritative Go reference — field semantics, defaults, validation rules, migration history. The YAML-authoring companion is /charly-vm:vms-catalog.

Source files

VmSpec (top-level shape)

type VmSpec struct {
    Source VmSource       // discriminated union: kind = cloud_image | bootc
    DiskSize string       // "20G", "10 GiB", "1T" — virtual size; the qcow2 is lazily/sparsely allocated
    Ram      string       // "4G", "8192M"
    Cpus     int
    Machine  string       // q35 | virt | i440fx — default: host-native
    Firmware string       // bios | uefi-insecure | uefi-secure — default: bios
    Backend  string       // auto | libvirt | qemu — pins the backend for this entity
    Autostart bool        // libvirt domain autostart (libvirt backend only)
    Network  *VmNetwork
    SSH      *VmSSH
    CloudInit *VmCloudInit
    Libvirt  *LibvirtDomain
}

Every field except Source, CloudInit, and Source-branch-specific subfields applies equally to both source kinds — the parity guarantee. Anything configurable for cloud_image VMs is configurable for bootc VMs, and vice versa.

Autostart (boot-start)

autostart: true sets libvirt's per-domain autostart flag (DomainSetAutostart, in runVmSpecCreate after define). Because VMs run under qemu:///session, that flag only fires at host boot once the session daemon is running — and there is no portable user-level virtqemud.socket to socket-activate it (Arch/CachyOS ships none). So ensureBootAutostartPrereqs (charly/vm.go) (a) runs loginctl enable-linger <user> (idempotent) and (b) writes + enables a per-VM user systemd oneshot charly-autostart-<domain>.service that runs virsh -c qemu:///session start <domain> at boot (WantedBy=default.target); virsh spawns the session daemon on demand and starts the already-defined domain — deterministic and cross-distro. charly vm destroy removes the unit (removeAutostartUserUnit). The libvirt flag is a domain property (not XML), so it survives DomainDefineXML redefinitions; runVmSpecCreate re-asserts both on every create/rebuild. The #Vm CUE schema rejects autostart: true with backend: qemu (if autostart { backend: "auto" | "libvirt" }). Additive optional field — no schema-version bump.

DiskSize is the virtual size: the bootstrap path's truncate + qemu-img convert -O qcow2 (no preallocation) produces a sparse qcow2 that grows on demand, so disk_size: 1T costs only the bytes actually written.

virtiofs shares — guest-user idmap

A libvirt.devices.filesystems[] entry with driver: virtiofs + accessmode: passthrough + a host-path source is auto-given a guest-user <idmap> at render time so the share is owned by the guest's interactive user (uid 1000), not guest-root. This is what makes source: /home/<you> → target: workspace usable as the SSH user inside the guest. Mechanism + the exact id partition live in /charly-internals:libvirt-renderer "virtiofs guest-user idmap"; shared-memory auto-pairing is in the same skill.

VmSource (discriminated union)

type VmSource struct {
    Kind string    // "cloud_image" | "bootc"

    // cloud_image branch:
    URL      string
    Checksum VmChecksum
    Cache    string
    BaseUser string       // adopt-user pattern — see below

    // bootc branch:
    Image      string     // `candy:` image entry name (carries base:/from:)
    Transport  string     // registry | containers-storage | oci | oci-archive
    Rootfs     string     // ext4 | xfs | btrfs
    RootSize   string     // "10G" — caps root partition, rest unpartitioned
    KernelArgs string
}

Kind is the discriminator. The #VmSource CUE disjunction (schema/vm.cue) enforces that exactly one branch's required fields are populated and forbids cross-branch fields (each arm pins kind and marks the others _|_).

Adopt-user decision (BaseUser)

BaseUser mirrors the container-side base_user: + user_policy: adopt pattern. When set:

1. /charly-internals:cloud-init-renderer::composeUsers emits users: [default, {name: <base_user>, ssh_authorized_keys: [...]}] — merge-by-name, no useradd.
2. spec.ssh.user defaults to BaseUser.
3. cloud-init appends the pubkey to ~<base_user>/.ssh/authorized_keys without touching sudoers/shell/home.

Common values: arch (Arch cloud image), ubuntu (Ubuntu Cloud), fedora (Fedora Cloud), debian (Debian Cloud), cloud-user (CentOS Cloud).

Leave empty only when the image has no default account — then declare a custom user in spec.cloud_init.users.

VmSSH / VmKeyInjection

type VmSSH struct {
    User         string   // default: cloud_image → "charly" OR base_user; bootc → "root"
    Port         int      // default: 2222
    KeySource    string   // auto | generate | none | <abs-path>
    KeyInjection *VmKeyInjection
}

type VmKeyInjection struct {
    SMBIOS    string  // auto | enabled | disabled
    CloudInit string  // auto | enabled | disabled
}

Dual-channel key injection is additive. Per-source-kind auto-defaults when KeyInjection is nil:

• cloud_image → {smbios: enabled, cloud_init: enabled} — belt + suspenders; cloud-init seed ISO is always emitted anyway.
• bootc → {smbios: enabled, cloud_init: disabled} — cloud-init seed ISO only emits when the guest has the cloud-init layer.

Having both channels on simultaneously is the safe default; there's no duplication cost at the guest (systemd-ssh-generator dedups entries in authorized_keys).

VmCloudInit (structured intent)

The renderer combines structured fields with renderer defaults:

• Packages: prepended with {openssh, curl, tar}.
• RunCmd: prepended with {systemctl enable --now sshd} so distro-specific setup can assume sshd is running.
• Users: the VmSSH.User account is auto-injected unless already present; if present, the renderer appends the ssh pubkey to the user's existing entry.

Extra is a raw-YAML escape hatch merged after structured fields. Prefer structured fields; Extra exists for long-tail cloud-init options the schema doesn't cover.

VmCharlyInstall strategies

type VmCharlyInstall struct {
    Strategy string  // auto | scp | url | skip
    URL      string  // when Strategy == "url"
    Checksum string  // "sha256:<hex>" for url strategy
}

Validation (charly/schema/vm.cue)

The closed #Vm CUE schema (registered via cue_kind_vm.go) enforces every VmSpec invariant — there is no Go VM validator. Key checks:

• source.kind ∈ {cloud_image, bootc, clone, imported, bootstrap}; the #VmSource disjunction requires each arm's fields and forbids cross-arm fields.
• firmware: ∈ {bios (default), uefi-insecure, uefi-secure}; uefi-secure ⇒ machine ≠ i440fx AND requires an explicit libvirt.features.smm: true.
• network.mode: ∈ {user (default), bridge, nat, network}; bridge ⇒ bridge: set.
• ssh.port ⊕ ssh.port_auto (mutually exclusive); ssh.key_source: ∈ {auto, generate, none} or an absolute path; ssh.key_injection.{smbios,cloud_init} ∈ {auto, enabled, disabled}.
• the #LibvirtDomain subtree is modeled + closed in the same schema (enums/ranges/ PCI-hex + cpu.mode:custom ⇒ model); see /charly-internals:libvirt-renderer.

Failed validation → hard load-time error (the closed schema also rejects unknown keys/typos); charly box validate runs the full concrete check.

Migration from legacy VmConfig

The legacy VmConfig type + BoxConfig.Vm + BoxConfig.Libvirt + ResolvedBox.Vm + LabelVm + LabelLibvirt were all deleted in the hard cutover. Field mapping for forensic purposes:

charly migrate performs this mapping idempotently. See /charly-build:migrate for the command and /charly-internals:cutover-policy for the policy.

Cross-References

• /charly-vm:vms-catalog — YAML-authoring companion (when to pick cloud_image vs bootc, adopt pattern, step-by-step recipes)
• /charly-internals:libvirt-renderer — LibvirtDomain rendering + pure render functions
• /charly-internals:cloud-init-renderer — RenderCloudInit, composeUsers, seed ISO
• /charly-internals:vm-deploy-target — VmDeployTarget consuming VmSpec via DeployExecutor
• /charly-internals:ovmf — ResolveOvmfForSpec reads spec.Firmware
• /charly-internals:cutover-policy — why the legacy surface was deleted in one PR
• /charly-vm:vm — command-family skill; reads vm.yml through VmSpec
• /charly-build:migrate — charly migrate command
• /charly-internals:go — Go CLI development overview