ProxStox

Read-only Proxmox inventory export CLI.

Canonical public name: ProxStox (not ProxSox).

Why it exists

ProxStox provides a practical way to collect live Proxmox inventory and export normalized machine-readable outputs for downstream tooling and automation.

Current status

• Active and evolving
• Real live read-only collection via Proxmox API (proxmoxer)
• Normalized exports with deterministic network/IP enrichment
• Designed for operator workflows and integration, not dashboard theater

Scope

• Proxmox-specific
• Read-only collection only
• CLI-first
• Config optional
• JSON/YAML/CSV/XML export
• Downstream export profiles (canonical, vmctl-ng, rollcall)

Authentication modes

• Username + password
• Username + interactive hidden password prompt (TTY required)
• API token (--token-id + --token-secret)

Install

pip install -e .

Usage

proxstox export -t 172.16.1.150 -u saar@pam -f yaml -o inventory.yml

Token mode (preferred for operations):

proxstox export -t 172.16.1.150 --token-id root@pam!inventory --token-secret '***' -f json

Export profile examples:

proxstox export -t 172.16.1.150 --token-id root@pam!inventory --token-secret '***' --profile vmctl-ng -f json
proxstox export -t 172.16.1.150 --token-id root@pam!inventory --token-secret '***' --profile rollcall -f json

Homelab/self-signed TLS testing:

proxstox export -t 172.16.1.150 --token-id root@pam!inventory --token-secret '***' --no-verify-tls -f yaml

Kind filtering

Supported: all, nodes, guests, qemu, lxc.

• all: nodes + guests
• nodes: nodes only
• guests: guests only
• qemu: qemu guests only
• lxc: lxc guests only

IP enrichment behavior

Guest IP/interface enrichment precedence:

1. QEMU live guest-agent interfaces (qga_live) for running QEMU guests
2. LXC runtime interfaces (lxc_runtime) for running containers
3. Config-derived guest IPs
   • QEMU Cloud-Init (ipconfigX) as cloudinit_config
   • LXC network config (netX) as lxc_config

primary_ip is deterministic:

• prefer non-loopback IPv4 from highest-precedence source
• then IPv6 when no IPv4 is available
• avoid loopback/link-local unless no better address exists

Security and safety notes

• ProxStox is read-only by design.
• Keep credentials outside version control.
• Prefer API tokens with least privilege.
• Use --no-verify-tls only for temporary homelab testing.

Limitations

• Guest network/IP details are best-effort and Proxmox-data-first.
• Missing optional fields do not fail export.
• Operational failures (auth/network/TLS/API/config) return clear stderr errors.

Documentation

See docs/ for architecture, auth, schema, and CLI behavior.