Proxmox nodes & onboarding

NexoVirt manages one or more Proxmox VE nodes or clusters from a single panel. Each Proxmox API connection you add is one standalone node or one whole cluster. This guide covers the Nodes list, the Add node wizard, the per-node page and removing a node again.

The Nodes list

Nodes in the main navigation lists every Proxmox node across all connections, one row per node, with its cluster, status, CPU / RAM / disk usage, guest count and agent state. The list refreshes every 30 seconds and can be filtered by Status (online, offline, pending) and Agent (OK, Update available, Not responding, Missing).

Badges next to the node name show Down (the node is unreachable, see failover), Maintenance and Inactive. A connection whose nodes have not been inventoried yet shows as a pending row (“Not inventoried yet”) with its setup actions (set up agent, test, edit, delete) directly in the row. Click a cluster badge to see only that cluster’s nodes.

Adding a node

Click Add node to open the three-step wizard: Connection, Agent setup and Install & scan.

1. Connection. Enter a Name (a friendly label), the Hostname / IP, Port (default 8006), User (default root), Realm (default pam) and Password of the Proxmox VE API. Leave Verify TLS certificate off for self-signed certificates. Click Test & Scan: the panel checks that the API is reachable, reads the PVE version, counts the nodes and checks that at least one storage can hold VM images. Next only unlocks when the node is reachable and its version is supported (Proxmox VE 7.0 or newer). A missing image-capable storage is a warning only.

2. Agent setup. Enter the SSH user (default root) and SSH port (default 22) and pick how to authenticate:

   • Root password: connect once with the node’s root SSH password.
   • Password SSH is disabled: use the panel’s key: copy the shown Panel public key into the node’s /root/.ssh/authorized_keys, then continue key-only.

   Generate & install an SSH key for passwordless future management is on by default (see Stored SSH credentials). Remember root password (encrypted) is optional.

3. Install & scan. The panel connects over SSH and shows each step live with a time estimate: connect via SSH (the host key is pinned), scan the node environment, ensure runtime dependencies (apt-get install -y php-cli only if PHP is missing), install the agent, install the system service, install the management SSH key, await the first heartbeat, provision the image storage, then scan system and PVE facts, the node firewall and the node networks. When it finishes, click Go to node.

Clusters are added as a whole

Connecting to any member of a Proxmox cluster adds all nodes of that cluster through that one connection. The agent is installed on the node you connected to. Features that run on the node itself (OS image downloads, node updates, DynDNS) work on that node; other cluster members show a message explaining that they need their own connection with an agent.

The API password is encrypted at rest and never shown back in the browser or returned by the API. The scan steps after the heartbeat are best-effort: if one fails it is marked as an error, but the agent is installed and the node is usable.

On Community Edition, adding a node is refused once the node limit is reached. See Editions & licensing.

The node page

Click a node in the Nodes list (or on the dashboard) to open its page. The page is built from the panel’s database, not a live Proxmox call, so it opens instantly and stays usable while the node is unreachable. The title shows the node status and an “as of <timestamp>” marker for the newest inventory data.

Four KPI cards at the top show CPU, Memory, Storage and Uptime (with kernel and network up/down rates), refreshed every 5 seconds from the collected metrics.

The header holds Switch node (for clusters), Backup jobs, Browse backups, Console and an Actions menu (Settings, Rescan node facts, Reboot node, Shut down node). Below that, the page has these tabs:

Tab	What it shows
Overview	Status (OS, PVE version, cluster, HA, Ceph), Health checks with inline fixes, and Recent activity. The tab shows a badge with the number of items that need attention.
Guests	The node’s guests (VMID, name, status, type), filterable by type and status.
Storage	Storage on this node with usage, the Proxmox VE storages and the scheduled Backup jobs.
Network	Network services tiles (NAT & port forwarding, WireGuard VPN, Firewall, Network map, IP zones, SDN projects), the Interfaces table with each bridge classified as WAN, Private, Internal or Other, the Firewall snapshot summary, the IPv4 forwarding switch and DynDNS. See Networking & NAT.
Hardware	PCIe devices (see PCIe passthrough), Disk health (SMART), Services and Updates (see Node updates).
Activity	Every guest event on this node, live-refreshing, with a View link to the real error detail of failed actions.
Settings	Connection, Agent, Operations (maintenance mode, evacuate) and removing the node from the panel. For a cluster, these settings apply to the whole cluster.

Health checks

The Overview tab lists problems first, then passing checks. Checks include the agent state, PVE version support, cluster quorum and offline cluster nodes, certificate expiry, available package updates (with an Install button), SMART disk health and the core PVE services (pve-cluster, pvedaemon, pveproxy, pvestatd). If the node has not been scanned yet, Scan now starts the first scan.

Rescanning node facts

System, hardware and PVE facts (and the health checks built from them) are refreshed by the background node facts scanner every 15 minutes through the agent. Actions > Rescan node facts starts a rescan immediately; it runs in the background and the facts update within a few minutes. A second rescan is refused while one is still running. Nodes whose agent is missing, not responding or outdated are skipped by the scanner, so update the agent if the facts stay empty.

Console, reboot and shutdown

Console opens a root shell on the node in the browser (xterm.js through the panel’s console proxy). The Proxmox session cookie stays on the server and every console session is recorded in the audit log.

Actions > Reboot node and Shut down node ask you to type the node name to confirm.

Maintenance mode and evacuation

Under Settings > Operations, Maintenance mode keeps new guests and incoming migrations off the node (or the whole cluster). While it is on, the node shows a Maintenance badge, it is hidden from the create wizard, guest creation through the API is refused, and it is not offered as a migration target. Evacuate migrates the running guests to other nodes and then turns maintenance mode on.

Connection settings

The Settings tab’s Connection card shows the API host, port, user, TLS state, whether the SSH host key is pinned, and the last successful contact. Test connection checks the API right away; Edit connection changes the stored details. When editing, leave the password blank to keep the current one.

SSH host key pinning

The node’s SSH host key is pinned on the first SSH connection, and every later SSH operation (update, remove, delete) verifies it. If the node was reinstalled, use Reset host key on the edit page. Changing the hostname or port clears the pinned key together with the stored SSH credentials, and the API password must then be entered again.

Stored SSH credentials

With Generate & install an SSH key for passwordless future management enabled, onboarding generates a per-node Ed25519 key pair, adds its public key to the node’s root authorized_keys and stores the key pair encrypted in the panel. If you also tick Remember root password (encrypted), the root password is stored encrypted too. With stored credentials, Update agent, Remove agent and the node wipe on Delete no longer ask for SSH credentials. Stored secrets are never shown in the browser or returned by the API.

Agent lifecycle

The Agent card on the Settings tab shows the agent state, installed version, the node it runs on and when it was installed or last updated.

• Set up agent runs the onboarding steps for a connection that has no agent yet.
• Update agent pushes the agent bundled with the panel, restarts it and waits for a heartbeat at the new version.
• Remove agent uninstalls the agent service, script and config from the node and revokes its token, but keeps the node, its inventory and metrics, so you can set the agent up again in one click. The panel’s SSH key stays in authorized_keys.

See The node agent for what the agent does.

Removing a node

Settings > Delete removes the connection (one node, or all nodes of a cluster) and all of its panel data: guest records, metrics, assignments and events. This cannot be undone.

By default only the panel data is removed and nothing on the node is touched. Turn on Also remove the agent, VPN, NAT and image storage from the node to also wipe the node: the agent, NexoVirt’s VPN and NAT, the nexovirt-images storage and the panel’s SSH key. The panel then connects over SSH; leave the SSH fields blank to use the credentials stored for this node. Without stored or entered credentials the wipe is refused and the node is kept.

Removing the agent (Remove agent, or the wipe switch on Delete) also removes NexoVirt’s WireGuard VPN and NAT from the node: the wg-nexovirt interface, the NexoVirt firewall chains and their services. Proxmox and your own firewall rules are not touched.

Caution

A delete without the wipe switch does not touch the node, so a running NexoVirt VPN or NAT stays active there. Disable them first, or turn the switch on.

Inventory

A background collector stores each connection’s nodes, guests, storages and networks every 5 minutes (a new row is written only when something changed). The node page, dashboard and guest list read from this inventory, so they show the last known state while a node is offline.

• Offline guests keep their last known IP address.
• Guests deleted in Proxmox drop out of the inventory automatically.

Next steps

• Create your first guest on the new node.
• Set up IP zones and NAT for the node’s networks.
• Review the REST API for node-level endpoints.