How to Monitor Proxmox VE With Zabbix (Beginner's Setup Guide)

If you've been running Proxmox VE for a while, you've probably gotten used to glancing at the little CPU and RAM graphs on the Summary tab and calling it a day. That's fine for a single box you check once a day. It falls apart the moment you have more than one node, or you want to know about a problem before you happen to open the browser tab.

Zabbix fixes that gap. It's a monitoring platform that's been around since 2001, it's free and open source, and it's not tied to Proxmox at all — which is actually the point. You can watch your Proxmox nodes, your network switch, your NAS, and your Pi-hole box from the same dashboard, with the same alerting rules.

This guide walks through the cleanest way to connect Zabbix to Proxmox VE: using Zabbix's official HTTP-based template, which talks to the Proxmox API directly. No agent installed on your hypervisor, no extra packages competing with Proxmox's own Debian base. Just an API token and a template.

What You Will Learn

What Zabbix actually does and how it's different from Proxmox's built-in graphs
How to create a locked-down, read-only API token in Proxmox VE
How to wire that token into Zabbix's Proxmox VE by HTTP template
How to confirm data is actually flowing, and what to do when it isn't
An optional add-on step for host-level metrics (disk space, load average) using the Zabbix agent

What Is This Feature?

Zabbix is a monitoring server. It polls things on a schedule, stores what it collects in a database, draws graphs from that history, and fires off alerts (email, Telegram, a webhook, whatever you've wired up) when a value crosses a threshold you define.

For Proxmox specifically, Zabbix ships an official template called Proxmox VE by HTTP. Instead of installing an agent on your Proxmox host, this template just calls the same REST API that the Proxmox web interface uses under the hood. It logs in with an API token, asks questions like "what's the CPU load on this node," "which VMs are running," "is any storage almost full," and turns the answers into Zabbix items, graphs, and triggers.

That's a meaningfully different approach from the agent-based monitoring covered in most general Linux monitoring guides. You're not installing software on the hypervisor — you're asking it questions over HTTPS, the same way your browser does.

Why Would You Use It?

Proxmox's own Summary tab is genuinely useful, but it has three limits that eventually bite everyone:

Short history. The built-in RRD graphs keep roughly a year of data at decreasing resolution, but there's no easy way to compare "this week vs. last month" across nodes without opening tab after tab.
No alerting. Proxmox will happily let a disk fill to 98% without telling you unless you've separately configured notifications for that specific condition.
One node at a time. If you've got a three-node cluster, or a cluster plus a couple of standalone boxes, you're checking each one individually.

Zabbix solves all three at once: long retention (years, if your disk allows it), configurable triggers with severity levels, and one dashboard that shows every host you've added, cluster or not. It's overkill for a single VM you spun up to test something. It stops being overkill the moment you're running actual services other people depend on.

Option	Setup effort	Alerting	Multi-node view
Built-in Proxmox graphs	None	Limited, manual	No — one node per tab
InfluxDB + Grafana	Moderate	Via Grafana alerting	Yes, with dashboard work
Zabbix (HTTP template)	Low — GUI-only, no agent	Built in, granular	Yes, native

None of these are wrong choices. If you already run Grafana for other things, stick with it. If you're starting from nothing and want alerting without building dashboards by hand, Zabbix gets you there faster.

Prerequisites

Before you start, make sure you've got:

A working Proxmox VE installation (this guide was written against 8.x and 9.x — the API hasn't changed in any way that matters here)
A Zabbix server already installed somewhere, version 6.0 or newer, since that's when the Proxmox VE by HTTP template became part of the official template set. It doesn't need to run on Proxmox itself — a small VM or LXC container elsewhere is fine, and honestly cleaner.
Admin access to the Proxmox web interface (to create an API token)
Admin access to the Zabbix frontend
Network connectivity from the Zabbix server to your Proxmox node on TCP port 8006 — check this now if the two live on different VLANs or behind a firewall, because it's the single most common thing that breaks this setup

You don't need root SSH access to Proxmox for any of this. Everything on the Proxmox side happens through the web GUI.

Step-by-Step Tutorial

Step 1: Create a Read-Only API Token in Proxmox

Zabbix only needs to read data from Proxmox — it never needs permission to start a VM or change a setting. So the first thing to do is create a user and token that can't do anything destructive, even if the token secret ever leaked.

In the Proxmox web interface, go to Datacenter → Permissions → Users and click Add. Create a user like zabbix@pve. You don't need to set a password — this account will only ever authenticate with an API token, not a login.

Next, go to Datacenter → Permissions → API Tokens and click Add. Pick the zabbix@pve user, give the token an ID such as monitoring, and pay attention to the Privilege Separation checkbox:

Leave it checked (the default) and the token gets its own permissions, separate from the user — you'll assign them next.
Uncheck it and the token simply inherits whatever the user account can do.

Either works for this guide. If you leave privilege separation on, go to Datacenter → Permissions, click Add → API Token Permission, set the path to /, pick the token you just created, and assign the PVEAuditor role. PVEAuditor is a built-in Proxmox role that can view basically everything — nodes, VMs, storage, cluster status — and change nothing. That's exactly the access level Zabbix needs.

When you save the token, Proxmox shows you the secret exactly once. Copy it somewhere safe right now — there's no way to view it again later, only regenerate it.

Step 2: Confirm the Template Exists in Zabbix

Log in to your Zabbix frontend and go to Data collection → Templates. Search for "Proxmox." You should see Proxmox VE by HTTP in the list already, since it ships with Zabbix by default from version 6.0 onward. If it's missing for some reason (an unusually stripped-down install, for example), you can pull it in from the official Zabbix template repository on GitHub and import it under Templates → Import.

Step 3: Create a Host for Your Proxmox Node

Go to Data collection → Hosts → Create host. Name it something sensible — the node's hostname is a good choice if you'll eventually add more nodes. Under Templates, search for and attach Proxmox VE by HTTP.

You don't need to configure an agent interface for this — the HTTP template talks over the network using an HTTP item type, not the Zabbix agent protocol, so there's no port 10050 involved here at all.

Step 4: Fill In the Macros

Click into the host you just created and open the Macros tab. Because you linked the template, it'll already list the macros the template needs, with placeholder values. You need to fill in three things:

The API URL for your Proxmox node — something like https://192.168.1.10:8006
The token ID, in the format zabbix@pve!monitoring
The token secret you copied in Step 1

Save the host. Give it a minute or two — Zabbix polls on its own schedule, it doesn't fetch instantly the moment you hit save.

Step 5: Check That Data Is Actually Coming In

Go to Monitoring → Latest data, filter by the host you created, and look for values under items like node CPU usage, memory usage, or uptime. If you see numbers updating, you're done with the core setup. If the fields are blank, jump to the Troubleshooting section below before doing anything else.

Step 6 (Optional): Add Host-Level Metrics With the Zabbix Agent

The HTTP template gives you Proxmox-specific data — node load, VM and container status, storage usage as Proxmox reports it. What it won't give you is raw Linux host detail like per-filesystem disk space or detailed process stats, because that's not something the Proxmox API exposes.

If you want that too, you can additionally install the Zabbix agent directly on the Proxmox host:

wget https://repo.zabbix.com/zabbix/7.0/release/debian/pool/main/z/zabbix-release/zabbix-release_latest_7.0+debian12_all.deb
dpkg -i zabbix-release_latest_7.0+debian12_all.deb
apt update
apt install zabbix-agent2
systemctl enable --now zabbix-agent2

Swap debian12 for debian13 if you're on Proxmox VE 9. After that, you'd add a second Zabbix host entry (or reuse the same one) with an Agent interface pointing at the node's IP on port 10050, and attach the standard Linux by Zabbix agent template. This step is genuinely optional — plenty of people run the HTTP template alone and never bother with this.

Commands Explained

Most of this setup is point-and-click, but a couple of commands are worth understanding if you want to script it or troubleshoot from a terminal.

To test that your API token actually works, before you even open Zabbix, run this from any machine that can reach your Proxmox node:

curl -k -H "Authorization: PVEAPIToken=zabbix@pve!monitoring=YOUR-SECRET-HERE" https://192.168.1.10:8006/api2/json/version

The -k flag tells curl to skip certificate verification, which you need here because Proxmox uses a self-signed certificate by default. If this returns a small JSON blob with a Proxmox version number, your token and permissions are correct — any problem you hit afterward in Zabbix is a Zabbix-side configuration issue, not a Proxmox one.

If you'd rather create the token from the command line instead of the GUI, this does the same thing as Step 1:

pveum user add zabbix@pve
pveum user token add zabbix@pve monitoring --privsep 0
pveum aclmod / -user zabbix@pve -role PVEAuditor

The --privsep 0 flag disables privilege separation on the token, so it just inherits whatever role you assign to the user with aclmod on the last line. It's the CLI equivalent of unchecking that box in the GUI.

Common Errors

A few things trip up almost everyone the first time through:

SSL certificate verify failed. Proxmox's default certificate isn't signed by a public CA, so Zabbix's HTTP item will reject it unless you tell it not to. Look for an Allow insecure server SSL certificate style option on the item or macro configuration and enable it, or replace Proxmox's certificate with one from a trusted CA if you'd rather fix it properly.
401 Unauthorized from the API. Almost always a typo in the token ID format — it needs the exclamation mark, like zabbix@pve!monitoring, not a colon or a dash. Double-check the secret was pasted in full too; it's a long string and easy to truncate on copy.
403 Forbidden, but the token authenticates fine. This means the token can log in but doesn't have the PVEAuditor role assigned, or you assigned the role to the wrong entity (the user instead of the token, when privilege separation is on).
Host shows as "not available" in Zabbix with no other detail. Check basic network reachability first — telnet 192.168.1.10 8006 from the Zabbix server, or just try loading the Proxmox web UI from that same machine's browser if it has one.

Troubleshooting

When data isn't showing up in Latest Data, work through this in order rather than guessing:

Re-run the curl command from the Commands Explained section, from the Zabbix server itself if possible. If that fails, nothing on the Zabbix side matters yet — fix connectivity and permissions first.
Check Reports → Latest problems and Monitoring → Latest data → Nothing found? messages — Zabbix usually tells you the actual HTTP error if you click into a specific item's history.
Look at the Zabbix server's own log, typically at /var/log/zabbix/zabbix_server.log, and search for the hostname you added. Timeout errors point to network or firewall issues; certificate errors point back to the SSL problem above.
Confirm the macros were saved correctly — it's easy to leave a trailing space after pasting a secret, which silently breaks authentication.
If only some items are populating and others aren't, that's usually normal — a handful of items in the template only apply to clustered nodes or specific storage types, so blanks there aren't necessarily broken.

Best Practices

Keep the token scoped to PVEAuditor and nothing more. There's no reason a monitoring system should ever be able to stop a VM, and a read-only token means a compromised Zabbix server can't be used to touch your infrastructure.

Don't alert on everything. A trigger that fires on 80% memory usage sounds responsible until you realize ZFS's ARC cache routinely uses most of your free RAM by design, and now you're getting paged for normal behavior. Start with a small number of triggers that matter — node down, disk over 90%, a VM that's supposed to be running but isn't — and add more as you learn what's actually noise on your setup.

If you're running a cluster, add each node as its own Zabbix host rather than trying to represent the whole cluster as one entry. Proxmox clusters don't have a single "cluster API endpoint" in the way this template expects — each node answers for itself.

Rotate the token secret occasionally, especially if you ever paste it somewhere you shouldn't have (a chat message, a public repo, a support forum post). Regenerating it in the Proxmox GUI takes seconds; cleaning up after a leaked credential takes a lot longer.

Frequently Asked Questions

Do I need to install anything on the Proxmox host itself?

No. The HTTP template talks to Proxmox's existing API over the network. Installing the Zabbix agent is a separate, optional step covered above, only needed if you also want raw OS-level metrics.

Will this slow down my Proxmox node?

No — the API calls Zabbix makes are the same lightweight calls the web interface itself uses, run on a polling interval measured in minutes, not seconds.

Can I monitor a whole cluster from one Zabbix host entry?

Not with a single entry. Add one Zabbix host per Proxmox node, all pointing at the same Zabbix server, and you'll get a combined view in the dashboard even though each is monitored individually.

Does this replace the built-in Proxmox graphs?

No, and it doesn't need to. The Summary tab is still the fastest way to check one node right now. Zabbix is for history, alerting, and looking at everything at once.

Is Zabbix actually free?

Yes. It's open source under the GPL, with no paid tier required for anything covered in this guide. Zabbix LLC does sell support contracts, but you don't need one.

What if I only have one Proxmox node — is this overkill?

Honestly, maybe. If it's a single homelab box and you're comfortable glancing at the Summary tab, you might not need this yet. It starts paying off the moment you'd rather get an alert than discover a full disk by accident.

Conclusion

Fifteen minutes of setup — a token, a template, three macros — gets you from "I hope nothing broke overnight" to actual alerting with history you can look back on. That's a good trade for most people running more than a toy VM.

Start small: get the node-level metrics flowing first, confirm alerts actually reach you (send yourself a test one), and only then decide whether the optional agent step is worth the extra moving part. Monitoring you don't trust is worse than no monitoring at all, because it teaches you to ignore it.

Vormox is an independent virtualization management platform built on Proxmox VE. Proxmox® and Proxmox VE® are trademarks of Proxmox Server Solutions GmbH. Vormox is not affiliated with, endorsed by, or sponsored by Proxmox.

How to Monitor Proxmox VE With Zabbix (A Beginner's Setup Guide)