{"id":16184,"library":"proxmox-api","title":"Proxmox API Client","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/UrielCh/proxmox-api","tags":["javascript","proxmox","client","typing","api","typescript","async","promise"],"install":[{"cmd":"npm install proxmox-api","lang":"bash","label":"npm"},{"cmd":"yarn add proxmox-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add proxmox-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the default export for initializing the API client. While CommonJS is supported, ESM imports are recommended for optimal tooling and type inference.","wrong":"const proxmoxApi = require('proxmox-api');","symbol":"proxmoxApi","correct":"import proxmoxApi from 'proxmox-api';"},{"note":"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.","wrong":"import ProxmoxEngine from 'proxmox-api';","symbol":"ProxmoxEngine","correct":"import { ProxmoxEngine } from 'proxmox-api';"},{"note":"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.","wrong":"require('tls').checkServerIdentity = () => {};","symbol":"NodeTLSRejectUnauthorized","correct":"process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';"}],"quickstart":{"code":"import proxmoxApi from \"proxmox-api\";\n\n// Authorize self-signed certificates if you are not using a valid SSL certificate.\n// In a production environment, prefer proper certificate validation or CA setup.\nprocess.env.NODE_TLS_REJECT_UNAUTHORIZED = process.env.PROXMOX_TLS_REJECT_UNAUTHORIZED || \"0\";\n\nasync function test() {\n    // Connect to Proxmox using environment variables for credentials.\n    // Replace with your actual Proxmox host, username, and password or API token details.\n    const proxmox = proxmoxApi({\n        host: process.env.PROXMOX_HOST ?? '127.0.0.1',\n        password: process.env.PROXMOX_PASSWORD ?? 'your-proxmox-password',\n        username: process.env.PROXMOX_USERNAME ?? 'root@pam'\n    });\n\n    try {\n        // List all nodes in the Proxmox cluster\n        const nodes = await proxmox.nodes.$get();\n        console.log(\"Proxmox Nodes:\", nodes.map((n: any) => n.node).join(', '));\n\n        // Iterate through each node to list its QEMU VMs\n        for (const node of nodes) {\n            const theNode = proxmox.nodes.$(node.node);\n            console.log(`\\n--- VMs on Node: ${node.node} ---`);\n\n            // List Qemu VMs on the current node with full details\n            const qemus = await theNode.qemu.$get({ full: true });\n\n            if (qemus.length === 0) {\n                console.log(`  No QEMU VMs found on node ${node.node}.`);\n                continue;\n            }\n\n            // Iterate through Qemu VMs to get their configuration\n            for (const qemu of qemus) {\n                const config = await theNode.qemu.$(qemu.vmid).config.$get();\n                console.log(`  VM Name: ${config.name}, VMID: ${qemu.vmid}, Memory: ${config.memory}MB, Cores: ${config.cores}`);\n            }\n        }\n    } catch (error) {\n        console.error(\"An error occurred:\", error);\n    }\n}\n\ntest().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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\"`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace `object.field-name` with `object['field-name']` for all API path segments that contain hyphens.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.1.0"},{"fix":"Explicitly specify the `port` option in the client configuration (`proxmoxApi({ host: '...', port: 8006, ... })`) to ensure consistent connectivity, regardless of library default changes.","message":"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.","severity":"gotcha","affected_versions":"<1.0.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Node.js by default rejects connections to servers presenting self-signed SSL certificates, which is common in Proxmox VE installations.","error":"Error: self-signed certificate in certificate chain"},{"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.","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).","error":"TypeError: Cannot read properties of undefined (reading '$get')"},{"fix":"Use bracket notation to access hyphenated API path segments: `proxmox.qemu.$(vmid).agent['get-fsinfo'].$get()`.","cause":"JavaScript's dot notation (`object.property`) does not support property names with hyphens. Proxmox API paths like `get-fsinfo` contain hyphens.","error":"TypeError: proxmox.qemu.vmid.agent.get-fsinfo.$get is not a function"}],"ecosystem":"npm"}