Configuration

Configuration

Everything is set through PROXIMO_* environment variables. Credentials are always passed by path — Proximo reads them at call time and never logs them. A full annotated example ships as packaging/proximo.env.example.

Core (PVE)

Variable	Required	Purpose
PROXIMO_API_BASE_URL	✅	https://host:8006/api2/json
PROXIMO_NODE	✅	Default node name
PROXIMO_TOKEN_PATH	✅	File containing USER@REALM!TOKENID=SECRET
PROXIMO_VERIFY_TLS		true (default). Never disable to work around a self-signed cert — pin or CA instead
PROXIMO_CA_BUNDLE		Path to a CA PEM (preferred over disabling TLS)
PROXIMO_FINGERPRINT		Exact-cert SHA-256 pin — see Certificate Pinning

Per-surface

Each of PBS / PMG / PDM has its own block, same shape (PROXIMO_PBS_*, PROXIMO_PMG_*, PROXIMO_PDM_*): a base URL, a credential path (_TOKEN_PATH, or _PASSWORD_PATH for PMG's ticket auth), and _VERIFY_TLS / _CA_BUNDLE / _FINGERPRINT. See the example file for the exact variable names per surface.

Trust-spine tuning (opt-in)

Variable	Turns on
PROXIMO_AUDIT_KEYED	Keyed HMAC ledger (default on; off downgrades — not recommended)
PROXIMO_AUDIT_EXPECTED_HEAD / PROXIMO_AUDIT_ANCHOR_*	Off-box head anchor for tail/wipe detection
PROXIMO_CONSENT_DIR (+ _TTL_SECONDS)	Independent, out-of-band mutation approval
PROXIMO_CONTAIN_TRIP_PATH	Kill-switch
PROXIMO_ARM_TTL (+ PROXIMO_TOKEN_PATH)	Write-arm expiry
PROXIMO_SCOPE_PATH	Restrict mutations to arm-time-declared targets
PROXIMO_FORBID, PROXIMO_RATE_MAX, PROXIMO_RATE_WINDOW	Forbid-list + rate/blast-radius budget
PROXIMO_TAINT_TRACK, PROXIMO_TAINT_FORBID, PROXIMO_TAINT_REQUIRE_CONSENT, PROXIMO_TAINT_FENCE	Prompt-injection coupling

Point every gate's *_DIR / *_PATH outside the agent's write reach — see the seam in Security Model. A gate the agent can write to is advisory, not a boundary.

Capability flags

Variable	Effect
PROXIMO_ENABLE_EXEC	Enables near-root ssh → pct exec (off by default; bounded by a CTID allowlist)
PROXIMO_ENABLE_AGENT	Enables in-guest qemu-agent ops (off by default; bounded by a VMID allowlist)
PROXIMO_SURFACES	Registers only the named planes (e.g. pve,exec) — context hygiene, not authorization

Multiple targets

To reach many boxes from one instance, define a target registry (TOML) where each entry carries its own base_url, credential path, TLS settings, and fingerprint. Tool calls then take an optional proximo_target= to pick a box. See packaging/targets.example.toml and Four Surfaces.