Reinstall, OS templates and the guest agent

Templates

Every Joy region has Compute Fabric nodes with prepared templates for Ubuntu 22.04, Ubuntu 24.04, Windows Server 2019, 2022 and 2025. Templates are verified per node — the deploy page and GET /api/v1/locations only offer operating systems whose template passed verification in that region. Templates are rebuilt monthly with current patches, the virtio drivers, cloud-init disabled (Joy configures the guest directly) and the QEMU guest agent installed and enabled.

What happens at install time

When you deploy, we make a full clone of the template (an independent disk, not a linked clone), resize it to your plan, set CPU and RAM, assign a MAC and reserve an IP from the regional pool, then boot. Once the guest agent answers, we use it to:

• write the static IPv4, gateway and DNS (netplan on Ubuntu, netsh on Windows);
• set the root / Administrator password to a freshly generated one;
• set the hostname; regenerate machine-id and SSH host keys; expand the filesystem;
• install your SSH key (Linux) and enable RDP with NLA (Windows).

Do not remove qemu-guest-agent (Ubuntu) or the QEMU Guest Agent service (Windows) — password resets, "Reapply network", graceful shutdowns and live stats depend on it.

Reinstall

Server page → Reinstall → choose an OS → type the hostname to confirm. Or POST /api/v1/instances/{id}/reinstall with {"os":"ubuntu-22"}.

What survives

• The IP address(es), gateway and rDNS.
• The VM id, the hostname (unless you pass a new one), the plan and billing.
• Backups stored in Joy backup space.

What is wiped

• The entire disk, including all data and all snapshots.
• The password (a new one is generated and shown in the console) and SSH host keys (expect a host-key warning on your next connection; clear it with ssh-keygen -R YOUR_IP).

Switching between Linux and Windows is allowed: Linux → Windows adds the licence add-on from the next invoice (and requires ≥ 2 GB RAM); Windows → Linux removes it.

Reinstall vs rollback vs rebuild

Custom images

Bring-your-own ISO is available on dedicated servers (via IPMI virtual media). On VPS we do not offer custom images yet; the practical alternative is to deploy Ubuntu, configure it with a script, and take a snapshot you can roll back to. Tell us by ticket which images you need — Debian and Rocky are on the list.

Troubleshooting

Reinstall stuck at "agent" — Windows templates can take up to five minutes on first boot; the job retries automatically once and then shows the error with a retry button. No network after reinstall — click "Reapply network" on the server page; if it fails, open the noVNC console and check the interface name against /etc/netplan/50-joy.yaml. Old host key warning — expected; remove the old entry.