Support

Help with ProxWatch

• Creating an API token
• Adding a server
• Certificates
• Alerts and muting
• Alerts on your phone
• Widgets
• Common problems

Creating an API token

ProxWatch connects with a Proxmox VE API token rather than your password. It's best to give it its own user, so you can see what it does and remove it at any time. Run these on any node, in a shell as root:

pveum user add monitor@pve --comment "ProxWatch"
pveum acl modify / --users monitor@pve --roles PVEAuditor
pveum user token add monitor@pve proxwatch --privsep 0

The last command prints the token's secret, a long ID like xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Proxmox only shows it once, so copy it now.

You can do the same in the web interface: create the user under Datacenter → Permissions → Users, give it the PVEAuditor role on / under Permissions, and add a token under API Tokens, with Privilege Separation unticked.

Which permissions to give it

To allow power controls, create a role with exactly the privileges ProxWatch uses and assign it instead of PVEAuditor:

pveum role add ProxWatch --privs "VM.Audit,Sys.Audit,Datastore.Audit,VM.PowerMgmt"
pveum acl modify / --users monitor@pve --roles ProxWatch

The health checks need Sys.Audit, which both options include. If a token is missing it, ProxWatch still shows status and load, but disk and certificate checks are skipped.

Privilege separation

The commands above turn privilege separation off, so the token has the same permissions as its user. If you'd rather keep it on (--privsep 1), the token needs permissions of its own:

pveum acl modify / --tokens 'monitor@pve!proxwatch' --roles PVEAuditor

Without them, Proxmox doesn't return an error. It returns an empty list, as if the server had no nodes. ProxWatch's Test button warns you when this happens.

Adding a server

1. Click the ProxWatch icon in the menu bar, then the gear button, and open Settings → Servers.
2. Click + and fill in:
   • Server: the address you use for the web interface, such as https://pve.local:8006. A bare IP address or hostname works too: ProxWatch adds https:// and port 8006.
   • API token ID: the user and token name joined by !, such as monitor@pve!proxwatch.
   • Token secret: the secret Proxmox showed when you created the token.
3. Click Fetch to read the server's certificate. See certificates below.
4. Click Test to check it works, then save.

The first time ProxWatch connects, macOS asks whether it can find devices on your local network. Choose Allow, or it won't be able to reach servers on your home or office network.

For a cluster, add any one node. ProxWatch sees every node, guest and datastore in the cluster through it. Add it once per cluster, not once per node. To keep watching if that node goes down, use an address that moves between nodes, such as a load-balanced or failover address, if you have one.

Certificates

Proxmox uses a self-signed certificate unless you've set up your own, and macOS doesn't trust self-signed certificates. ProxWatch gives you two ways to connect anyway.

Pin the certificate (recommended)

Click Fetch when adding a server. ProxWatch reads the certificate's SHA-256 fingerprint and fills it in. Check it matches the one Proxmox shows under Node → System → Certificates (double-click pveproxy-ssl.pem, or pve-ssl.pem if there isn't one), then save. From then on, ProxWatch only accepts that exact certificate, and refuses to connect if it changes.

When you renew or replace the certificate, the fingerprint changes and ProxWatch shows a certificate error. Open the server in Settings, click Fetch again, check the new fingerprint and save.

Accept any self-signed certificate

Turn on Accept any self-signed certificate to skip pinning. It's simpler, but ProxWatch can't then tell your server from another device pretending to be it, so only use it on a network you trust.

If your server has a certificate from a public authority, such as one from Let's Encrypt set up through Proxmox's ACME support, you don't need either option.

Alerts and muting

Thresholds are in Settings → Alerts. CPU and memory alerts only fire after several checks in a row over the threshold, so a short spike doesn't trigger one. The disk, ZFS, update, certificate and backup checks run every 5 minutes.

• Mute until resolved: right-click an issue in the panel, or click Mute Until Resolved on its notification. You won't hear about it again until it's fixed and comes back.
• Never alert: right-click an issue, or open a node or guest and click Never Alert, to stop all alerts for that resource. Useful for a test VM that's always busy.
• Snooze: click the bell at the bottom of the panel to snooze every alert for 1 hour, 4 hours or until tomorrow morning. Issues still show in the panel.

To undo mutes, click Unmute All in Settings → Alerts.

Unexpected stops: when a guest stops, ProxWatch checks Proxmox's task log for a stop, shutdown, migration, backup or similar task that explains it. If there isn't one, and you didn't stop it from ProxWatch, you get an alert. A guest that crashes, runs out of memory, or that something outside Proxmox shuts down is reported.

Alerts on your phone

ProxWatch can send alerts on to your phone or another service. Set it up in Settings → Notifications → Forwarding, then click Send Test. Forwarding follows your snoozes and mutes. You can forward only critical alerts, and choose whether to include recoveries.

ProxWatch does the checking itself, so forwarded alerts only arrive while your Mac is awake and ProxWatch is running.

ntfy

1. Install the ntfy app on your phone and subscribe to a topic. Anyone who knows a topic's name on ntfy.sh can read it, so pick a long, hard-to-guess name.
2. In ProxWatch, choose ntfy and enter the topic's URL, such as https://ntfy.sh/your-topic-name. If you run your own ntfy server, use its address instead.
3. If your topic needs an access token, enter it under Access token.

Critical alerts are sent with urgent priority, and warnings with high priority.

Webhook

Choose Webhook and enter a URL. ProxWatch sends each alert as a JSON POST, with an optional access token as a Bearer authorisation header:

{
  "server": "Homelab",
  "title": "pve2: ZFS pool rpool is DEGRADED",
  "body": "…",
  "severity": "critical",      // ok, warning or critical
  "kind": "raised",            // raised, escalated, resolved, guestStopped, taskFailed,
                               // connectionLost or connectionRestored
  "resource": "node/pve2",
  "timestamp": "2026-11-01T03:12:00Z"
}

That works with Home Assistant's webhook automations, n8n, and most automation tools.

Widgets

Right-click your desktop, choose Edit Widgets, and search for ProxWatch. There are three:

• Server Status shows one server. To choose which, right-click it and choose Edit "Server Status".
• All Servers lists every server you monitor, worst first.
• VM or Container shows one guest: whether it's running, its CPU and memory over the last few minutes, and any issues. Right-click it and choose Edit "VM or Container", then pick a guest from the list, or type to search. Clicking it opens that guest in Proxmox.

The server and guest widgets also come as Server Gauges and VM or Container Gauges, which show CPU, memory and storage as rings instead of bars. To use rings in the menu bar panel too, choose Rings under Settings → General → Show usage as.

The list of VMs and containers to choose from comes from ProxWatch, so open it at least once after adding a server.

Widgets show what ProxWatch last saw, so ProxWatch needs to be running for them to stay current. If it hasn't checked for over 10 minutes, the widget says it's stale. Turn on Launch at login in Settings → General to keep it running.

Common problems

"Nothing is visible", or the server looks empty

Usually the token has privilege separation on but no permissions of its own, or its role isn't assigned on /. See privilege separation above.

Disk, ZFS or certificate checks are missing

The token needs Sys.Audit. The PVEAuditor role includes it, so check the role is assigned on /, not on a single node or pool.

Starting or stopping a guest says permission denied

The token needs VM.PowerMgmt for that guest. See which permissions to give it.

A certificate error after it was working

The server's certificate has changed, usually because it was renewed. If you expected that, fetch the new fingerprint as described in certificates. If you didn't, check before trusting it.

It can't connect to a server on my network

• Check you allowed local network access: System Settings → Privacy & Security → Local Network, and make sure ProxWatch is on.
• Check the address opens the Proxmox web interface in a browser on the same Mac.
• If you use a VPN such as Tailscale or WireGuard to reach the server, check it's connected.

I don't get notifications

Check System Settings → Notifications → ProxWatch allows notifications, that alerts aren't snoozed (the bell at the bottom of the panel), and that the issue or resource isn't muted. Focus modes can also hold notifications back.

Try it without a server

Click Try It with Demo Data in the panel to explore two sample clusters with live-updating numbers and a few problems. Power actions in the demo are simulated. Click the purple DEMO badge to leave.