Quickstart

Quickstart

Five minutes from nothing to an AI agent that can read your Proxmox — and not one byte more until you decide otherwise. The order matters: you build the boundary first, then hand over the keys.

1. Install

uvx proximo-proxmox --help        # zero-install run
# or
pipx install proximo-proxmox      # persistent CLI
# or Docker:  docker run --rm ghcr.io/john-broadway/proximo doctor

The pip package is proximo-proxmox; the command and import stay proximo.

2. Mint a least-privilege token in Proxmox

This is the load-bearing step. The token is the floor your keys never leave — Proximo can never do more than it allows, because Proxmox enforces that server-side.

In the Proxmox web UI: Datacenter → Permissions → API Tokens → Add. Create a token for a dedicated user, and give it a read-only role to begin (e.g. PVEAuditor on /). Copy the secret when it's shown — it's shown once. Save it to a file:

mkdir -p ~/.config/proximo
printf 'USER@REALM!TOKENID=SECRET' > ~/.config/proximo/token   # exact format, no newline
chmod 600 ~/.config/proximo/token

Proximo reads the token from that path at call time and never logs it.

3. Point Proximo at your server

export PROXIMO_API_BASE_URL="https://your-pve.example.lan:8006/api2/json"
export PROXIMO_NODE="your-node-name"
export PROXIMO_TOKEN_PATH="$HOME/.config/proximo/token"

Self-signed certificate? Don't disable TLS. Point at the CA, or pin the cert:

export PROXIMO_CA_BUNDLE="$HOME/.config/proximo/pve-ca.pem"   # the cluster CA, or…
export PROXIMO_FINGERPRINT="AB:CD:…"                          # the cert's SHA-256 — see Certificate Pinning

4. Verify your boundary — before any AI sees it

proximo doctor

doctor is a read-only preflight. It reports what your token can and cannot do, and the trust spine's state — which pillars stand and which sockets are empty. Read it. This is you confirming the floor holds before you build anything on top of it.

5. Wire Proximo into your AI client

Proximo speaks MCP over stdio. In an MCP client (Claude Desktop, Cursor, Cline, …) add a server entry that runs proximo with the PROXIMO_* environment above. It runs on your machine, on demand — no daemon, no open port.

6. Grant scoped write — when you're ready

Only when you've watched the read-only surface behave, widen the token's role in Proxmox to exactly the write surface you mean to hand over. Everything above the token — The Trust Spine and the opt-in controls — is what makes that write productive and accountable. The token is what makes it safe.

Pull the keys anytime: revoke or downgrade the token in Proxmox. The floor answers to Proxmox, not to Proximo — nothing in the agent's reach can undo that.

More detail lives in SETUP.md.