# Runtime Dependencies

This file tracks host and guest dependency expectations for Sysadmin Chronicles.
Keep it updated when provisioning scripts, VM display backends, or installer
requirements change.

## Host Packages

| Capability | Arch package / command | Minimum tested version | Notes |
| --- | --- | --- | --- |
| Godot runtime | `godot` | 4.6.2 | Used for the current Godot client path. |
| Libvirt CLI | `libvirt` / `virsh` | 12.2.0 | Use `qemu:///system` for game VMs. Socket activation is supported. |
| QEMU system emulator | `qemu-system-x86` / `qemu-system-x86_64` | 11.0.0 | Must match the split QEMU module package versions. |
| QEMU disk tools | `qemu-img` | 11.0.0 | Used by VM builders for qcow2 images. |
| QXL display module | `qemu-hw-display-qxl` | 11.0.0 | Required for `virt-install --video qxl`. |
| Virtio GPU modules | `qemu-hw-display-virtio-gpu`, `qemu-hw-display-virtio-gpu-pci`, `qemu-hw-display-virtio-vga` | 11.0.0 | Required for the default SPICE + virtio workstation display path. |
| SPICE UI module | `qemu-ui-spice-core` | 11.0.0 | Required for SPICE graphics in libvirt domain capabilities. |
| SPICE channel module | `qemu-chardev-spice` | 11.0.0 | Required for SPICE agent channels. |
| SPICE audio module | `qemu-audio-spice` | 11.0.0 | Required for SPICE-backed guest audio. |
| VM installer | `virt-install` | 5.1.0 | Creates imported cloud-image domains. |
| SPICE viewer | `remote-viewer` / `virt-viewer` | 11.0 | Used for desktop workstation display. |
| Cloud image tools | `cloud-image-utils`, `cdrtools`, `libisoburn` | cloud-image-utils 0.33, cdrtools 3.02a09, libisoburn 1.5.8 | Used to generate seed ISOs. |
| SSH client | `ssh` | OpenSSH 10.3p1 | Used by the game and setup scripts to reach guests. |
| Node.js | `node` | 22.22.2 | Required by the redesigned browser HUD/server path. |

## Libvirt Resources

| Resource | Required shape | Notes |
| --- | --- | --- |
| Network | `sc-internal`, bridge `sc-br0`, subnet `10.42.0.0/24`, NAT forwarding | NAT is required during VM image provisioning so Debian cloud-init can install packages. The network remains private to libvirt guests for inbound access. |
| Storage pool | `sc-images` | For `qemu:///system`, defaults to `/var/lib/libvirt/images/sysadmin-chronicles`. |
| SSH key | `~/.ssh/sc_host_key` | Injected into guests for game automation and bridge access. |

## Workstation Guest Packages

The workstation image currently targets Debian 12 Bookworm and installs:

- Desktop/display: `xfce4`, `xfce4-goodies`, `lightdm`, `lightdm-gtk-greeter`, `spice-vdagent`, `qemu-guest-agent`, `accountsservice`, `linux-image-amd64`
- Desktop metadata: `gvfs`, `gvfs-daemons`, `libglib2.0-bin` for trusted desktop launchers and GVFS metadata writes
- User tools: `tilix`, `chromium`, `thunar`, `geany`, `meld`, `vim`, `nano`, `tmux`, `htop`
- Sysadmin tools: `openssh-server`, `openssh-client`, `sudo`, `curl`, `wget`, `rsync`, `git`, `jq`, `python3`, `nmap`, `netcat-openbsd`, `dnsutils`, `traceroute`, `mtr`, `tcpdump`, `strace`, `lsof`, `openssl`, `whois`, `iperf3`, `logwatch`
- Fonts/completion: `fonts-hack`, `fonts-firacode`, `bash-completion`

## Version Capture

Before cutting an installer or release, capture current versions with:

```bash
tools/setup/check-host.sh
virsh --connect qemu:///system version
qemu-system-x86_64 --version
virt-install --version
pacman -Q libvirt qemu-system-x86 qemu-hw-display-qxl qemu-hw-display-virtio-gpu qemu-hw-display-virtio-gpu-pci qemu-hw-display-virtio-vga qemu-ui-spice-core qemu-chardev-spice qemu-audio-spice virt-install virt-viewer spice-gtk cloud-image-utils cdrtools libisoburn
```