Registry / devops / proxmox-api

proxmox-api

JSON →
library1.1.1jsnpmunverified

proxmox-api is a comprehensive JavaScript and TypeScript client library for interacting with the Proxmox VE API. Currently stable at version `1.1.1`, it offers a unique mapping approach where Proxmox API paths are directly translated into chained method calls (e.g., `/nodes/mynode` becomes `proxmox.nodes.mynode`). The library's core differentiator is its 100% mapping of available Proxmox API calls, complete with extensive TypeScript typings that enable rich IntelliSense, significantly reducing the need to consult external API documentation. It features a small footprint, weighing less than 10KB including its integrated documentation. Releases appear to be ad-hoc but frequent, driven by bug fixes and compatibility updates, such as recent enhancements for ESM and Proxmox 8 support. It supports multiple authentication methods including username/password and API tokens.

npm install proxmox-api
INSTALL
IMPORT
SIG · PROXMOX-API
P
proxmox-api
devopsjavascriptv1.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

proxmoxApi
import proxmoxApi from 'proxmox-api';
const proxmoxApi = require('proxmox-api');
This is the default export for initializing the API client. While CommonJS is supported, ESM imports are recommended for optimal tooling and type inference.
ProxmoxEngine
import { ProxmoxEngine } from 'proxmox-api';
import ProxmoxEngine from 'proxmox-api';
ProxmoxEngine is a named export, typically used when you need direct access to the underlying engine object, such as for sharing an authenticated session or for advanced configuration.
NodeTLSRejectUnauthorized
process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
require('tls').checkServerIdentity = () => {};
While not a direct import from the package, setting `NODE_TLS_REJECT_UNAUTHORIZED` is a common pattern for local Proxmox development due to self-signed certificates. This should be handled with caution in production environments.

This quickstart demonstrates how to initialize the Proxmox API client, connect to a Proxmox host (using environment variables for sensitive data), list all cluster nodes, and then iterate through each node to retrieve and log configuration details for all running QEMU virtual machines.

import proxmoxApi from "proxmox-api"; // Authorize self-signed certificates if you are not using a valid SSL certificate. // In a production environment, prefer proper certificate validation or CA setup. process.env.NODE_TLS_REJECT_UNAUTHORIZED = process.env.PROXMOX_TLS_REJECT_UNAUTHORIZED || "0"; async function test() { // Connect to Proxmox using environment variables for credentials. // Replace with your actual Proxmox host, username, and password or API token details. const proxmox = proxmoxApi({ host: process.env.PROXMOX_HOST ?? '127.0.0.1', password: process.env.PROXMOX_PASSWORD ?? 'your-proxmox-password', username: process.env.PROXMOX_USERNAME ?? 'root@pam' }); try { // List all nodes in the Proxmox cluster const nodes = await proxmox.nodes.$get(); console.log("Proxmox Nodes:", nodes.map((n: any) => n.node).join(', ')); // Iterate through each node to list its QEMU VMs for (const node of nodes) { const theNode = proxmox.nodes.$(node.node); console.log(`\n--- VMs on Node: ${node.node} ---`); // List Qemu VMs on the current node with full details const qemus = await theNode.qemu.$get({ full: true }); if (qemus.length === 0) { console.log(` No QEMU VMs found on node ${node.node}.`); continue; } // Iterate through Qemu VMs to get their configuration for (const qemu of qemus) { const config = await theNode.qemu.$(qemu.vmid).config.$get(); console.log(` VM Name: ${config.name}, VMID: ${qemu.vmid}, Memory: ${config.memory}MB, Cores: ${config.cores}`); } } } catch (error) { console.error("An error occurred:", error); } } test().catch(console.error);
Debug
Known issues
gotchaWhen connecting to Proxmox with a self-signed SSL certificate, Node.js will by default reject the connection due to `DEPTH_ZERO_SELF_SIGNED_CERT` errors. The library documentation suggests setting `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"`.
fix
For development, set `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";` before initializing the client. In production, configure proper SSL certificate validation or use a trusted CA.
affects: >=1.0.0
gotchaProxmox API paths containing hyphens, such as `/qemu/{vmid}/agent/get-fsinfo`, must be accessed using bracket notation for the hyphenated segment (e.g., `theNode.qemu.$(vmid).agent['get-fsinfo'].$get()`). Direct dot notation will result in a runtime error.
fix
Replace `object.field-name` with `object['field-name']` for all API path segments that contain hyphens.
affects: >=1.0.0
breakingEarly versions of `proxmox-api` (prior to `1.1.0` and `1.0.1`) had known issues with ESM (ECMAScript Module) and CommonJS (CJS) compatibility, leading to potential import or runtime errors depending on your module system setup.
fix
Ensure you are using `proxmox-api@1.1.0` or later for improved ESM compatibility and robust CJS support. Review your `tsconfig.json` and `package.json` for correct module resolution settings if issues persist.
affects: <1.1.0
gotchaThe default port used for connections was changed in version `1.0.2` to adhere to standard HTTP/HTTPS ports. If your environment relied on a non-standard implicit default port in earlier versions, connections might break without explicit port configuration.
fix
Explicitly specify the `port` option in the client configuration (`proxmoxApi({ host: '...', port: 8006, ... })`) to ensure consistent connectivity, regardless of library default changes.
affects: <1.0.2
Errors
Common errors & fixes
Error: self-signed certificate in certificate chain
Node.js by default rejects connections to servers presenting self-signed SSL certificates, which is common in Proxmox VE installations.
fix
Set `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";` in your application's entry point before initializing the `proxmox-api` client. For production, consider using a trusted certificate or properly configuring your environment's CA certificates.
TypeError: Cannot read properties of undefined (reading '$get')
This typically occurs when attempting to call an HTTP method (`.$get()`, `.$post()`, etc.) on an API path that is either invalid, incomplete, or incorrectly formed (e.g., missing a required path parameter or a misspelled segment).
fix
Double-check the API path mapping against the Proxmox API Viewer (e.g., `proxmox.nodes.$(node.name).qemu.$(vmid).config.$get()`) and ensure all dynamic segments (`$(variable)`) are correctly provided. Verify the path matches the official Proxmox API structure.
TypeError: proxmox.qemu.vmid.agent.get-fsinfo.$get is not a function
JavaScript's dot notation (`object.property`) does not support property names with hyphens. Proxmox API paths like `get-fsinfo` contain hyphens.
fix
Use bracket notation to access hyphenated API path segments: `proxmox.qemu.$(vmid).agent['get-fsinfo'].$get()`.
Upgrade
Version history
1.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
Resources
proxmox-api — npm install proxmox-api · libregistry