Inside the Proxmox VE API: Three Request Paths Explained

pveproxy, pvedaemon, and pvesh all provide access to Proxmox VE API functions, but they are not interchangeable. They differ in network exposure, permission context, and how callers reach the API.

API coverage alone does not distinguish the two daemons: both are documented as exposing the complete API. The more useful questions are where a request enters, whether that path is network-facing, and which account provides the required privileges.

Roles at a glance

A concise mental model is:

• pveproxy is the external HTTPS entry point.
• pvedaemon is the local, root-privileged API daemon.
• pvesh is the root-only local shell interface.

pveproxy: the HTTPS-facing proxy

pveproxy exposes the complete Proxmox VE API over HTTPS on TCP port 8006. It runs as www-data with “very limited permissions,” and operations requiring more permissions are forwarded to the local pvedaemon (pveproxy(8)).

Its documented role includes:

• accepting HTTPS API connections on port 8006;
• exposing the complete API through that endpoint;
• operating under a limited account rather than as root;
• forwarding operations that require greater permissions to pvedaemon; and
• forwarding requests addressed to other cluster nodes.

That last behavior allows a client to manage a cluster while connected to one Proxmox VE node. If a request targets another node, pveproxy automatically forwards it to that node (pveproxy(8)).

This does not mean every request follows an identical internal route. The manual identifies privileged-operation forwarding and cross-node forwarding, but it does not provide a request-by-request execution map.

pvedaemon: the local privileged daemon

pvedaemon also exposes the complete Proxmox VE API, but on 127.0.0.1:85. Its manual says the daemon listens on a local address only and cannot be accessed from outside the node; external API exposure belongs to pveproxy (pvedaemon(8)).

The second distinction is privilege. pvedaemon runs as root and is documented as having permission to perform all privileged operations (pvedaemon(8)).

Together, the daemon manuals describe a clear separation:

1. pveproxy accepts HTTPS API traffic under the limited www-data account.
2. Operations requiring more permission can be forwarded to the node-local service.
3. pvedaemon provides that local API service under root.

Calling pvedaemon another public API endpoint would therefore be misleading. “Complete API” describes its API coverage; 127.0.0.1:85 defines its documented network boundary.

pvesh: direct API invocation from the shell

pvesh is not another API daemon. It is a command-line management tool that invokes Proxmox VE API functions directly, without using the REST/HTTPS server. Only root is allowed to use this direct path (pvesh(1)).

Its main commands correspond to API operations:

• pvesh get calls GET;
• pvesh create calls POST;
• pvesh set calls PUT;
• pvesh delete calls DELETE;
• pvesh ls lists child objects at an API path; and
• pvesh usage displays usage information for an API path.

For example, the manual shows how to list cluster nodes:

pvesh get /nodes

It also demonstrates how to inspect the available options for an API path:

pvesh usage cluster/options -v

These are direct local invocations rather than HTTPS requests to pveproxy on port 8006 (pvesh(1)).

Applying the distinction to API failures

These boundaries provide a useful first step when investigating API access problems.

A remote HTTPS client cannot connect

The documented network-facing service is pveproxy on TCP port 8006. pvedaemon is not an alternative remote endpoint because it listens only on 127.0.0.1:85 (pveproxy(8); pvedaemon(8)).

That identifies the relevant service boundary, not the specific cause. These manuals alone cannot determine whether a particular failure involves the socket, network policy, TLS configuration, or another deployment-specific condition.

HTTPS works, but an operation fails

Because pveproxy has limited permissions and forwards operations requiring more permission to pvedaemon, the local privileged boundary may be relevant. A failed operation by itself, however, does not establish where the failure occurred or prove that the request reached pvedaemon.

pvesh works while remote access does not

A successful pvesh invocation shows that root could call the API function directly without the REST/HTTPS server. It does not demonstrate that pveproxy, its HTTPS path, or cross-node forwarding is working.

A request targets another cluster node

Forwarding requests to their target nodes is part of pveproxy’s documented role (pveproxy(8)). The supplied manuals do not describe enough implementation or failure behavior to attribute every cross-node problem to a particular mechanism.

Scope of this distinction

These three manuals establish access surfaces, network boundaries, and permission contexts. They do not explain authentication internals, deployment-specific firewall behavior, or asynchronous task creation and completion.

The comparison is based on the supplied Proxmox VE 9.2.13 manual pages. No live socket inspection or request trace was performed.

Sources

• pveproxy(8) — PVE API Proxy Daemon
• pvedaemon(8) — PVE API Daemon
• pvesh(1) — Shell interface for the Proxmox VE API

Sources and further reading

• https://pve.proxmox.com/pve-docs/pveproxy.8.html
• https://pve.proxmox.com/pve-docs/pvedaemon.8.html
• https://pve.proxmox.com/pve-docs/pvesh.1.html