tools.proxmox_tools module

Proxmox VE hypervisor control via the Proxmox REST API.

Uses the proxmoxer library (see requirements.txt). Authenticate with either a password (user like root@pam) or an API token (user like root@pam!tokenid and password as the token secret).

Security: requires UNSANDBOXED_EXEC — controls foundational infrastructure.

TLS verification is disabled by default (typical self-signed Proxmox certs); use only on trusted networks or terminate TLS elsewhere.

async tools.proxmox_tools.run(host='', user='', password='', node='', action='', vmid=None, snapshot_name=None, credential_profile='', ctx=None)[source]

Authorize, validate, and execute one Proxmox VE control action, returning JSON.

Handler for the proxmox_control tool — the public entry point for VM lifecycle and snapshot operations on a Proxmox hypervisor. It enforces the privilege gate, optionally hydrates connection details from a saved credential profile, validates every field, then runs the blocking Proxmox call off the event loop and serialises the result (truncating oversized payloads).

It gates on _check_priv() (the UNSANDBOXED_EXEC privilege, resolved against Redis). When credential_profile is given it loads and decrypts that profile via tools._credential_profile_store.load_profile() (reading the Redis hash stargazer:proxmox_credentials:{user_id}) and overlays explicit kwargs with tools._credential_profile_store.merge_profile(). It checks action against _VALID_ACTIONS and validates host/user/node/snapshot with _host_ok(), _user_ok(), _node_ok(), and _snapshot_name_ok(), requiring vmid for every action except list_vms. The real proxmoxer work — which makes live HTTP calls to the hypervisor and can mutate VM state — is run via asyncio.to_thread(_proxmox_dispatch, ...) so the loop is not blocked. Results larger than _MAX_JSON_CHARS are replaced with a “narrow the request” error. This function mutates no module state of its own.

Registered in the module TOOLS list as the proxmox_control handler and dispatched by tool_loader.py; no direct in-repo Python callers.

Parameters:

  • host (str) – Proxmox API host; required unless supplied via credential_profile.

  • user (str) – Auth user/realm, e.g. root@pam or root@pam!tokenid.

  • password (str) – Account password or API-token secret (required).

  • node (str) – Cluster node name to target.

  • action (str) – One of _VALID_ACTIONS (list_vms, start_vm, stop_vm, reset_vm, create_snapshot, rollback_snapshot, destroy_vm).

  • vmid (int | None) – Target QEMU VM id; required for every action except list_vms.

  • snapshot_name (str | None) – Snapshot name; required for the snapshot and rollback actions.

  • credential_profile (str) – Name of a saved profile to load host/user/ password/node from; explicit kwargs override the loaded values.

  • ctx (Any) – The tool ToolContext supplying redis, config, and user_id; None yields a “No context.” error.

Returns:

A JSON result string — the dispatch payload (with success and action-specific keys) on success, or a JSON error for missing context, denied privilege, a bad profile load, an invalid action/host/user/node/ snapshot, a missing required vmid, or an over-limit response.

Return type:

str