[TUTORIAL] HiveStation — Developer Workstation for Proxmox Virtual Environment

[aureladmin]

HiveStation — Developer Workstation for Proxmox Virtual Environment

HiveStation is a community project that automates the full installation of a developer workstation built on Proxmox VE 9 on top of Debian 13 (Trixie), using a set of 8 bash scripts (S1 → S8). It is inspired by the Proxmox VE wiki article "Developer Workstations with Proxmox VE and X11".

The goal: a reproducible, scriptable workstation where Proxmox VE runs the VMs/containers and a full desktop environment runs on the same machine — with snapshots, optional high availability, themed boot, and a monitoring widget. The scripts are bilingual (FR / EN).

HiveStation is an independent community project. It is not affiliated with or endorsed by Proxmox Server Solutions GmbH. Proxmox is a registered trademark of Proxmox Server Solutions GmbH.

Disk modes (chosen at S1 launch)

The installer is no longer limited to Btrfs RAID1. A single marker file (/etc/hivestation/install.conf) written by S1 is the single source of truth, and every following script (S2 → S8) adapts to the selected mode automatically.

Mode	Disks	Layout	VM/CT storage	System snapshots	HA
single	1	Btrfs (single/dup)	Btrfs subvolumes	Snapper + grub-btrfs	No
RAID1	2	Btrfs (raid1)	Btrfs subvolumes	Snapper + grub-btrfs	Yes (full)
LVM + EXT4	1	LVM + ext4 root	LVM-thin pool (local-lvm)	Timeshift (RSYNC)	No

• single — one disk, Btrfs with dedicated subvolumes, bootable Snapper snapshots. No HA.
• RAID1 — two identical disks, Btrfs RAID1 with full high availability: two synced EFI partitions (the system stays bootable if a disk fails), SWAP failover, and automatic replacement of a missing Btrfs member.
• LVM + EXT4 — one disk, classic Proxmox LVM layout: VG pve with an ext4 root, swap, and an LVM-thin data pool declared as Proxmox local-lvm. VM/CT snapshots are native LVM-thin; system snapshots use Timeshift.

Installation workflow (S1 → S8)

Script	Phase	Runs from
S1	Debian base install (Btrfs or LVM) + GRUB + network	Debian Live
S2	HA scripts (RAID1) + SSH	Debian Live (same session)
S3.1	Proxmox kernel + PVE subvolumes (Btrfs)	Installed Debian
S3.2	Proxmox VE (+ local-lvm in LVM) + optional PCI(e) passthrough	Installed Debian (PVE kernel)
S4	Graphical interface + Flatpak (optional)	Installed Proxmox
S5	Snapshots: Snapper+grub-btrfs (Btrfs) or Timeshift (LVM)	Installed Proxmox
S6	Firmware + NVIDIA drivers (optional)	Installed Proxmox
S7	vmbr0 + DHCP + NAT + boot optimization	Installed Proxmox
S8	Themes, tools, monitoring widget (menu, optional)	Installed Proxmox

The process involves a few reboots (after S2, S3.1, S3.2, S7); the scripts tell you exactly when. Debian is installed via debootstrap from the Live environment, then the Proxmox kernel and the proxmox-ve package are layered on top.

Features

• Snapshots — Btrfs modes: Snapper + grub-btrfs expose bootable snapshots in the GRUB menu, with per-subvolume retention. S5 also creates a baseline snapshot so the full chain is validated before the first reboot. LVM mode: Timeshift (RSYNC) for the system, LVM-thin for VMs/CTs.
• Networking — vmbr0 bridge with dynamic NAT toward the WAN interface (ethernet or Wi-Fi), DHCP detection, and NetworkManager-wait-online timeout reduced to 5 s.
• Graphical environment (optional) — GNOME, KDE, XFCE, LMDE7 Cinnamon or COSMIC, with Flatpak + Flathub. In Btrfs modes the display manager gets its own subvolume for clean snapshot isolation.
• Firmware & NVIDIA (optional) — AMDGPU, Intel Wi-Fi, Realtek; NVIDIA open kernel modules (recommended, Turing+) or proprietary (legacy GPUs), plus an optional XanMod kernel. Wayland/X11 PRIME offload handled.
• Boot themes & tools (optional, S8) — HiveStation GRUB theme, adaptive Plymouth splash (single/RAID1/LVM), asusctl, supergfxctl, a GNOME Cinnamon-like setup (Nemo optional), and a GNOME monitoring widget.
• Monitoring widget — disk-mode aware — a desktop overlay showing CPU/temp, RAM/swap, AMD iGPU + NVIDIA dGPU, network, Proxmox VMs/services, and a storage panel that adapts to the disk mode: "Btrfs single" / "Btrfs RAID1" / "LVM / EXT4" (with an LVM-thin usage bar), plus Snapper or Timeshift snapshots accordingly.
• Custom branding — drop a logo.png next to S8 and it is auto-injected into GRUB, Plymouth, and the GNOME extension.

Requirements

• CPU: x86_64, multi-core with VT-x/AMD-V recommended
• RAM: 4 GB minimum, 16 GB+ recommended
• Disks: 1 (single Btrfs or LVM+EXT4), or 2 identical SSD/NVMe for RAID1 + HA
• Firmware: UEFI (Secure Boot optional)
• Network: internet access is mandatory before S1 (debootstrap downloads packages); configure the network in the Live session first

Warning: S1 completely wipes the selected disk(s) — one disk in single/LVM mode, two in RAID1. All existing data is lost.

Why Btrfs (and LVM as an alternative)?

Btrfs gives free, bootable, per-subvolume snapshots (Snapper + grub-btrfs) and a simple two-disk RAID1 with self-healing — ideal for a workstation you want to roll back safely. For people who prefer the classic Proxmox stack or a single-disk setup without Btrfs, the LVM + EXT4 mode provides an LVM-thin pool for VM/CT snapshots and Timeshift for the system. ZFS is intentionally not used here to keep the footprint light on a single-workstation install.

Download & usage

The full package (scripts S1–S8, GRUB/Plymouth themes, GNOME monitoring widget, the gnome-cinnamon-like helper, and the installation guide) is attached to this post. Boot Debian 13 Live, configure the network, copy the scripts to a single directory, then run them in order (sudo bash S1-…sh). The guide documents every step, the three disk modes, post-install operations, and troubleshooting.

Feedback, questions, and test reports are very welcome. Thanks to everyone who has tested and commented in this thread.

 

[aureladmin]

Please give me feedback if you do any tests or encounter any errors.

 

[aureladmin]

Update V15 : 19/03/2026

 

[Johannes S]

Why btrfs instead of zfs? Wouldn't it make sense to be able to use ZFS-only features?

 

[aureladmin]

Why btrfs instead of zfs? Wouldn't it make sense to be able to use ZFS-only features?

I've been trying to do this with ZFS for a while now, but I'm running into bugs that aren't currently solvable. For example, zfsbootmenu doesn't work when used with the pre-compiled Void EFI image; no snapshot is visible at boot due to modifications made by the Proxmox VE installation. Creating the EFI image from scratch makes it even worse. Zfsbootmenu was developed primarily for Void; it works with other distributions, but I haven't found a solution for this particular problem.

Another point: I'm using this configuration on a laptop, and ZFS is extremely slow at startup, shutdown, and during daily use. The CPU load is between 5 and 10% higher. The same issue with RAM persisted. Even after trying to modify the ARC cache to minimize RAM usage, I experienced crashes. I had to allocate a minimum of 4GB to ARC for it to function, so ultimately, whithout any VM, RAM usage quickly climbed to around 8GB.

I couldn't get the laptop to boot even if a disk failed. If you use ZFS with Proxmox tools, it won't boot if the boot disk is faulty; you have to use the command line to resolve the problem. Without Proxmox tools, it's also impossible because once the ZFS partition is degraded, there's no way to boot from a mirror (it works on a RAIDZ1 array with three disks, but not in a mirror configuration, I don't know why).

There are other issues as well, but basically, that's why I chose BTRFS instead of ZFS.

If someone manages to solve the three biggest problems I mentioned, I would obviously use ZFS, but currently it's not possible in my case.

The reason I started this project, in case anyone asks, is that I had a problem with an SSD in late 2025 (both the boot and system SSD), and I wasted time reinstalling everything (no data loss).

 

[aureladmin]

Update to V17

 

[fruchtzwerg]

I tried using the scripts. I got stuck after selecting the disks: ./S1-17V0.sh: line 378 sgdisk: command not found
gdisk is already installed

Edit: The failure was to run the script as root without sudo. Succeeded with sudo bash S1-17V0.sh

 

[aureladmin]

I just ran another test on version 17 and I'm not encountering this problem.

 

[aureladmin]

Update to V18 — three disk modes (single Btrfs, RAID1 Btrfs, LVM + EXT4)

What's new (highlights):

• Three disk modes selectable at S1 launch: single Btrfs, RAID1 Btrfs (HA), or LVM + EXT4.
• LVM mode: VG pve (ext4 root + swap + LVM-thin pool declared as local-lvm); system snapshots via Timeshift.
• Monitoring widget is now disk-mode aware (Btrfs single/RAID1 or LVM/EXT4; Snapper or Timeshift).
• GNOME Cinnamon-like: Nemo is now optional (keep Nautilus, install Nemo, or revert).
• S5 creates a baseline snapshot so you can validate the snapshot chain before the first reboot.

V18 is a significant update. The biggest change is that the installer is no longer limited to Btrfs RAID1: at S1 launch you now choose between three disk modes. A single marker file (/etc/hivestation/install.conf) written by S1 is the single source of truth, and every following script (S2 → S8) adapts to the selected mode automatically.

Disk modes (chosen in S1)

Mode	Disks	Layout	Snapshots	HA
Single	1	Btrfs -d single -m dup (label prox_single)	Snapper + grub-btrfs	No
RAID1	2	Btrfs -d raid1 -m raid1 (label prox_raid1)	Snapper + grub-btrfs	Full (EFI sync, SWAP failover, auto-replace)
LVM + EXT4	1	VG pve = root (ext4) + swap + LVM-thin "data"	LVM-thin (VMs) + Timeshift (system)	No

New: LVM + EXT4 mode

For those who prefer the classic Proxmox LVM layout over Btrfs, V18 adds a single-disk LVM + EXT4 mode:

• EFI partition + one LVM PV; volume group pve containing root (ext4, label prox_lvm), swap, and a data LVM-thin pool for VM/CT disks.
• The thin pool is automatically declared as the Proxmox local-lvm storage (S3.2).
• VM/CT snapshots are handled natively by the LVM-thin pool. System (root) snapshots use Timeshift in RSYNC mode, installed automatically by S5 (since Snapper and grub-btrfs are Btrfs-only).
• GRUB is configured with the lvm module preloaded; no degraded flag, no subvol rootflags.

Every Btrfs-specific step (PVE subvolumes, Display Manager subvolume isolation, Snapper, grub-btrfs) now detects a non-Btrfs root, prints a clear warning, and skips cleanly without aborting the script. So the graphical environments (GNOME, KDE, XFCE, LMDE7 Cinnamon, COSMIC) install normally in LVM mode too — only the optional Btrfs subvolume isolation is skipped.

Other improvements

• S5 baseline snapshot — in Btrfs mode, S5 now creates an initial baseline snapshot and regenerates grub-btrfs.cfg at the end of setup, so you can validate the full Snapper + grub-btrfs + boot-menu chain before the first reboot.
• GNOME Cinnamon-like — Nemo is now optional. A single menu offers: (1) keep Nautilus as default (theme + extensions still applied), (2) install Nemo and set it as default, or (3) revert to default Nautilus (file manager only, with an option to uninstall Nemo).
• Monitoring widget v2 — disk-mode aware. The GNOME overlay now adapts its storage panel to the disk mode: "Btrfs single" / "Btrfs RAID1" / "LVM / EXT4" (with an LVM-thin usage bar), and shows Snapper or Timeshift snapshots accordingly.
• Robustness fixes — reworked DHCP detection in S1, marker-based architecture for cross-script consistency, more robust grub-btrfs.cfg regeneration, and a snapshot-count fix in S5.

The rest of the workflow is unchanged: vmbr0 + dynamic NAT, NVIDIA driver options (open kernel modules recommended), optional XanMod kernel, PCI(e) passthrough, custom GRUB/Plymouth themes, and asusctl/supergfxctl.

Version

Current version: V18
All scripts remain bilingual (French / English). A full English guide is included in the archive.

As always, feedback and test reports are very welcome.

Download: see attachment below (HIVESTATION-V18-COMPLETE.tar.gz).

 

[bl1mp]

Do you support disk encryption?
Unfortunately the PVE installer does not, so instead of generating a PVE-autoinstall iso, with first-boot-script, I usually install the Debian by hand and PVE afterwards.
For a server that is absolutely fine, but for my portable developmemt workstations (aka Laptop) that would be a super nice feature.

 

[aureladmin]

Do you support disk encryption?
Unfortunately the PVE installer does not, so instead of generating a PVE-autoinstall iso, with first-boot-script, I usually install the Debian by hand and PVE afterwards.
For a server that is absolutely fine, but for my portable developmemt workstations (aka Laptop) that would be a super nice feature.

It's planned for later, but I still need to validate the two methods I have in testing with all the possibilities of file systems so as not to have to maintain too many different methods and I also need to think about future developments other than those I have planned, zfs for example on which I am stuck at the moment.
Unfortunately, I only have one laptop on which I can perform physical tests and it is my main computer; I have to take it apart every time, which takes me a lot of time.