Skip to main content

Proxmox AIops (preview)

Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by Proxmox Server Solutions GmbH. "Proxmox" is a trademark of its owner. MIT licensed.

AI-powered Proxmox VE VM and container lifecycle operations with a built-in governance harness — unified audit log, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. Self-contained: no external dependencies beyond proxmoxer and the MCP SDK. Preview — not yet full coverage of every Proxmox operation.

What works

  • CLI (proxmox-aiops ...): vm list/get/config/start/stop/shutdown/reboot/reconfigure/clone/delete/migrate, vm resize-disk/move-disk/agent-ping, vm snapshot-create/snapshot-delete/snapshot-list/snapshot-rollback, backup create/list/restore, ct list/start/stop, cluster nodes/status/task-status/resources/node-status/task-log/next-vmid, ha status/resources, pool list/members, firewall vm-rules/cluster-status, storage list/content, init, secret set/list/rm/migrate/rotate-password, doctor, mcp.
  • MCP server (proxmox-aiops mcp or proxmox-aiops-mcp): 39 tools, every one wrapped with the bundled @governed_tool harness.
  • Credentials: proxmox-aiops init (onboarding wizard) and proxmox-aiops secret ... manage an encrypted secret store — no plaintext passwords in config.yaml.
  • Reversibility: write ops with a clean inverse (start/stop/shutdown/reconfigure/clone/migrate/snapshot-create/move-disk, container start/stop, and restore-into-a-free-vmid) record an inverse undo descriptor; irreversible ops (delete, snapshot-rollback, forced restore) declare none and are tagged high risk. Disk resize is grow-only (shrink refused).
  • Async tasks: Proxmox writes return a task UPID — poll completion with cluster task-status / read lines with cluster task-log (the runaway budget guard prevents poll loops from running away).

Quick start

uv tool install proxmox-aiops
mkdir -p ~/.proxmox-aiops
# create ~/.proxmox-aiops/config.yaml with a targets: list
# put secrets in ~/.proxmox-aiops/.env  (chmod 600)
proxmox-aiops doctor

Example ~/.proxmox-aiops/config.yaml:

targets:
  - name: pve-lab
    host: 10.0.0.10
    user: "root@pam!claude"   # API token: user@realm!tokenid
    node: pve1
    auth_kind: token
    verify_ssl: false          # self-signed lab certs only

~/.proxmox-aiops/.env (chmod 600): PROXMOX_PVE_LAB_SECRET=<token-uuid>

Audit & safety

All operations are logged to a local SQLite audit DB under ~/.proxmox-aiops/ (relocatable via PROXMOX_AIOPS_HOME). Every write tool passes through the governance harness: policy pre-check, token/runaway budget guard, graduated risk-tier gate, and audit logging. Destructive CLI commands (vm stop, vm delete, vm snapshot-delete, vm snapshot-rollback, ct stop) require double confirmation and support --dry-run (notably backup restore, which is high risk). API-returned text is run through a prompt-injection sanitizer.

Contributing & feature requests

This is a preview — coverage is intentionally focused. Missing a device, action, or feature you need? Open an issue or pull request at github.com/AIops-tools/Proxmox-AIops — feature requests, contributions, and comments are all welcome.

License: MIT.

Metadata

Release files for proxmox-aiops 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for proxmox-aiops 0.2.1
File Size Uploaded Provenance Actions
proxmox_aiops-0.2.1.tar.gz 88.4 kB Without provenance Details for proxmox_aiops-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for proxmox-aiops 0.2.1
File Interpreter ABI Platform Actions
proxmox_aiops-0.2.1-py3-none-any.whl Python 3 none any Details for proxmox_aiops-0.2.1-py3-none-any.whl

Total release size: 173.0 kB

Release files / proxmox_aiops-0.2.1.tar.gz

Download URL proxmox_aiops-0.2.1.tar.gz
Size 88.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8db350380c6e169a56ee0621b4da2f8a7cdd06028300a91c192b46713ac8f2f0
BLAKE2b-256 checksum
How to use checksums
0d262eaac568d0672ed9033969df4e8acc83e6c9e02c006863100aa74535a33a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / proxmox_aiops-0.2.1-py3-none-any.whl

Download URL proxmox_aiops-0.2.1-py3-none-any.whl
Size 84.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4e3bce4d1b935b315155b30688884696c34b8b07ceedfae2559399f65ae82b77
BLAKE2b-256 checksum
How to use checksums
ab483b2df81c44246a4fe12e48524d414f7ad080d54f9f40e0222dbd6c2d73f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for proxmox-aiops 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page