Deploying a Proxmox VE Worker Node on an Air-Gapped Network

Deploying a Proxmox VE worker node on an air-gapped network means building an offline apt repository, moving packages over with a USB stick, and joining the cluster blind. The official docs cover the repo part but skip the cluster join, and the forum threads are a mess. Here’s the full walkthrough.

Build the offline repository

On an internet-connected Proxmox VE 8 machine, install apt-mirror and mirror the pve-no-subscription repo. The config lives in /etc/apt/mirror.list. Mine looks like this:

deb http://download.proxmox.com/debian/pve bookworm pve-no-subscription

Run apt-mirror and wait. It pulls about 2GB. Then copy the whole /var/spool/apt-mirror/mirror/download.proxmox.com directory to a USB drive. That’s your offline repo.

Set up the air-gapped node

Install Proxmox VE from the ISO like normal. It’ll complain about no network for updates — ignore that. Plug in the USB and mount it:

mount /dev/sdb1 /mnt

Create a local repo file at /etc/apt/sources.list.d/pve-local.list:

deb [trusted=yes] file:/mnt/pve bookworm pve-no-subscription

Run apt update. It should read from the local mirror without touching the internet. Install any missing packages with apt install.

Join the cluster

On the existing cluster, get the join info:

pvecm updatecerts --force
pvecm status

Copy the cluster name and the IP of an existing node. On the new worker, run:

pvecm add <existing-node-ip> --link0 <local-ip>

You’ll get a warning about no SSH key exchange — that’s expected offline. Type yes and enter the root password of the existing node. It should join within a minute. Check with pvecm status on any node.

My take

The offline repo part is straightforward if you’ve used apt-mirror before. The cluster join is where it gets annoying — the docs assume you have internet for key exchange. Just use --link0 and ignore the warning. This is a pain in the butt but doable in under an hour.

If you’d rather not deal with USB drives, a cheap managed switch with a temporary internet VLAN on one port works too. But for a truly air-gapped setup, this is the way.

Related: Proxmox Random Reboots: Check the PSU, RAM, Kernel, Watchdog, and Heat in That Order