Proxmox API Client

Common errors

• Error: self-signed certificate in certificate chain

  cause 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')

  cause 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

  cause 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()`.

Warnings

• gotcha When 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.
• gotcha Proxmox 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.
• breaking Early 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.
• gotcha The 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.

Install

• npm install proxmox-api npm
• yarn add proxmox-api yarn
• pnpm add proxmox-api pnpm

Imports

• proxmoxApi
  wrong:

  const proxmoxApi = require('proxmox-api');

  correct:

  import proxmoxApi from '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
  wrong:

  import ProxmoxEngine from 'proxmox-api';

  correct:

  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
  wrong:

  require('tls').checkServerIdentity = () => {};

  correct:

  process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

  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.

Quickstart

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);