Run a command inside an LXC (ssh -> pct exec). MUTATION-CAPABLE.

Dry-run by default: without confirm=True you get a PLAN — the command plus a heuristic read-vs-write / destructive-pattern classification (advisory only) — recorded to the ledger. Re-call with confirm=True to execute. Disabled unless PROXIMO_ENABLE_EXEC is set (safe default is API-only). Allowlist-scoped (fail-closed) and audited.

snapshot=True (UNDO): take an auto-undo snapshot first and WAIT for it; if it can't be made (e.g. storage doesn't support snapshots) the command is NOT run (fail-closed). On success the result carries an undo_point you can revert with pve_rollback.

Run SQL via psql inside a container (as the db OS user). MUTATION-CAPABLE.

Dry-run by default: without confirm=True you get a PLAN — the SQL plus a heuristic read/DML/DDL classification (advisory only) — recorded to the ledger. Re-call with confirm=True to execute.

snapshot=True (UNDO): take an auto-undo snapshot first and WAIT for it; if it can't be made the SQL is NOT run (fail-closed). On success the result carries an undo_point (revert via pve_rollback).

Verify the tamper-evident audit ledger's hash chain — PROVE the log is intact.

Pass expected_head (the head() value you pinned off-box) to also catch tail truncation, a forged tail-append, or a full file replacement — a forward walk alone can't see those. Falls back to PROXIMO_AUDIT_EXPECTED_HEAD when omitted.

MUTATION: run a command inside a guest via the qemu-agent (async, polls for result).

Dry-run by default: without confirm=True you get a PLAN recorded to the ledger. Re-call with confirm=True to execute.

Requires PROXIMO_ENABLE_AGENT=1 and the VMID in PROXIMO_AGENT_ALLOWLIST. The command runs INSIDE the guest OS — no undo primitive on this plane.

Returns status="ok" only when the agent reports the process exited. Returns status="running" with pid when the poll deadline is reached before exit.

List all PBS datastores (read-only). Returns datastore objects with store name, backend type, and mount status. Use pbs_datastore_status for runtime usage statistics or pbs_datastore_get for full configuration. Needs PROXIMO_PBS_* config.

Get runtime usage statistics for one PBS datastore (read-only). Returns total capacity, used bytes, and available bytes. Use pbs_datastores_list to enumerate datastores (with backend type) or pbs_gc_status for garbage-collection state.

Get garbage-collection status for one PBS datastore (read-only). Returns current GC state, disk/index statistics, and pending/removed chunk counts (the GC schedule field appears only when a schedule is configured on the datastore). Use pbs_gc_start to execute garbage collection or pbs_datastore_status for capacity.

READ-ONLY: list backup snapshots in a PBS datastore with optional filters. Returns snapshot metadata including backup type, ID, timestamp, size, owner, and protection status; filter by namespace, backup_type (vm/ct/host), or backup_id. To delete one use pbs_snapshot_delete; to change its protected flag or notes use pbs_snapshot_protected_set or pbs_snapshot_notes_set.

List namespaces within a PBS datastore with optional hierarchical filtering (read-only). Returns each namespace's hierarchical path (the ns field); optionally filter by parent namespace or limit recursion depth. Use pbs_namespace_create to add namespaces.

READ-ONLY: list all PBS remote sync-sources. Returns a list of remote config dicts; passwords are never included (PBS never returns them, and this strips defensively too). Use pbs_remote_get for one remote's config. Needs PROXIMO_PBS_* config.

READ-ONLY: get the config of one PBS remote sync-source by name. Returns a dict; no password returned. Use pbs_remotes_list to list all remotes, or pbs_remote_update to change this one. Needs PROXIMO_PBS_* config.

READ-ONLY: list all PBS traffic-control bandwidth-limit rules. Returns active rules with their rate-in/rate-out limits, network targets, and comment. Use pbs_traffic_control_upsert to create or modify rules. Needs PROXIMO_PBS_* config.

READ-ONLY: list all PBS scheduled jobs of the given type. job_type = sync|verify|prune. Returns all jobs with their configs; raises on invalid job_type. Use pbs_job_create, pbs_job_update, or pbs_job_delete to manage one. Needs PROXIMO_PBS_* config.

READ-ONLY: list PBS tasks on a node. Defaults to 'localhost' (standard single-node PBS name). Returns a list of task dicts; filter running=True for active tasks or errors=True for failed ones. Use this to check on a UPID returned by pbs_gc_start, pbs_verify_start, pbs_datastore_create, or pbs_datastore_delete. Needs PROXIMO_PBS_* config.

Get full config of one PBS datastore by name (read). Returns path, gc-schedule, etc. For runtime usage stats use pbs_datastore_status instead. Needs PROXIMO_PBS_* config.

MUTATION (HIGH): start garbage collection on a PBS datastore. Dry-run by default — GC permanently removes unreferenced chunks (no undo). confirm=True to execute; returns the UPID (async task) — check progress with pbs_gc_status or pbs_tasks_list.

MUTATION: start an integrity verification run on a PBS datastore. Dry-run by default — non-destructive (read-only check) but heavy I/O. confirm=True to execute; returns the UPID (async task) — check progress with pbs_tasks_list.

MUTATION: prune backup snapshots per a retention policy. TWO safety gates: confirm (Proximo dry-run vs execute) AND dry_run (PBS-side preview). dry_run=True (default) only previews; dry_run=False DELETES recovery points (PLAN is HIGH, no undo). confirm=True to execute. Synchronous — returns prune decisions. For one specific snapshot use pbs_snapshot_delete instead.

MUTATION (HIGH): delete a specific backup snapshot (a recovery point) from a PBS datastore. Dry-run by default. Permanent — no undo. confirm=True to execute. Synchronous. To shield a snapshot instead of deleting it use pbs_snapshot_protected_set(protected=True); for bulk retention-based deletion use pbs_prune.

MUTATION: create a namespace within a PBS datastore. Dry-run by default (additive, LOW). confirm=True to execute — returns {"status": "ok", "result": null}. Use pbs_namespaces_list to check for name collisions first, or pbs_namespace_delete to remove one.

MUTATION: delete a namespace from a PBS datastore. Dry-run by default — delete_groups=True is HIGH (it deletes all backup groups/snapshots inside the namespace, no undo). confirm=True to execute — returns {"status": "ok", "result": null}. Use pbs_namespaces_list to confirm it's empty first, or pbs_namespace_create to recreate an empty namespace afterward.

MUTATION (MEDIUM): create a new PBS datastore at the given path.

Dry-run by default — additive, but a misconfigured path can conflict with existing storage. PBS datastore creation is an async worker task (UPID) → outcome='submitted' (not 'ok'). No rollback primitive. confirm=True to execute. Use pbs_datastores_list to check for name/path collisions first, or pbs_datastore_update to modify it afterward.

POST /config/datastore Smoke-confirm: gc-schedule / prune-schedule / notification-mode param names; sync-vs-async.

MUTATION (MEDIUM): update PBS datastore configuration. Dry-run by default.

CAPTURE: reads current config before planning; on read failure the plan is marked incomplete. Changing gc-schedule / prune-schedule affects data retention cluster-wide. No rollback primitive — revert by re-applying the captured config. confirm=True to execute. Use pbs_datastore_get to inspect current config, or pbs_datastore_delete to remove the datastore instead.

PUT /config/datastore/{name} Smoke-confirm: accepted param names (hyphenated vs underscored).

MUTATION: delete a PBS datastore. Dry-run by default. RISK IS CONDITIONAL:

destroy_data=False (default) → MEDIUM: detaches the datastore config; backup CHUNKS REMAIN ON DISK and the datastore is re-addable to recover. destroy_data=True → HIGH, IRREVERSIBLE: PERMANENTLY DESTROYS ALL backup data in the named datastore — no recovery possible.

PBS deletion is an async worker task (UPID) → outcome='submitted'. confirm=True to execute. To recover from a destroy_data=False detach, re-add with pbs_datastore_create at the same path.

DELETE /config/datastore/{name} Smoke-confirm: destroy-data / keep-job-configs param names; sync-vs-async.

MUTATION: set or clear the protected flag on a PBS snapshot. RISK IS CONDITIONAL:

protected=True → LOW: shields the snapshot from pruning and GC (protective). protected=False → HIGH: SILENTLY re-enables pruning/GC — this recovery point can now be auto-deleted by the next prune job or GC run. No undo once auto-deleted.

No PBS snapshot primitive for rollback. Dry-run by default. confirm=True to execute. To annotate rather than protect a snapshot use pbs_snapshot_notes_set; to delete it outright use pbs_snapshot_delete.

PUT /admin/datastore/{store}/protected Smoke-confirm: exact path + param names (backup-type, backup-id, backup-time, protected).

MUTATION (LOW): annotate a PBS snapshot with notes. Dry-run by default.

CAPTURE: reads current notes before planning; on failure the plan is marked incomplete. Does not affect backup data, retention, or protection — to shield the snapshot from pruning/GC use pbs_snapshot_protected_set instead. No PBS snapshot primitive — revert by re-applying the captured notes. confirm=True to execute.

PUT /admin/datastore/{store}/notes Smoke-confirm: exact endpoint path + param names (backup-type, backup-id, backup-time).

MUTATION (MEDIUM): reassign the owner of a PBS backup group. Dry-run by default.

The new owner controls deletion and prune of this backup group. The previous owner loses those permissions immediately. Use pbs_snapshots_list to see the group's current owner first. No PBS snapshot primitive — revert by re-assigning the owner back. confirm=True to execute.

POST /admin/datastore/{store}/change-owner Smoke-confirm: exact path + new-owner vs owner param name.

MUTATION (MEDIUM): create a PBS remote sync-source. Dry-run by default.

PRIVATE PASSWORD REDACTION: 'password' is a remote user credential. It is UNCONDITIONALLY redacted from the server-side plan, change, current state, detail, and audit ledger. Only {"password":"[redacted]"} is recorded on those surfaces. L02 NOTE: the MCP tool-call itself is a structured JSON object in which 'password' appears as a plain parameter — it is visible in the LLM's output token stream and in any MCP client log. This is an MCP-protocol property; server-side redaction protects the ledger only. The TLS cert 'fingerprint' is PUBLIC data — it is NOT redacted.

No rollback primitive — revert by deleting the remote (pbs_remote_delete). confirm=True to execute.

POST /config/remote Smoke-confirm: auth-id vs authid param name; port param name.

MUTATION (MEDIUM): update an existing PBS remote. Dry-run by default.

CAPTURE: reads current (non-secret) config before planning; on failure plan is marked incomplete. PRIVATE PASSWORD REDACTION: if 'password' is provided it is UNCONDITIONALLY redacted from the server-side plan, change, current state, detail, and audit ledger. L02 NOTE: the MCP tool-call itself is a structured JSON object in which 'password' appears as a plain parameter — visible in the LLM's output token stream and any MCP client log. This is an MCP-protocol property; server-side redaction protects the ledger only. The TLS cert 'fingerprint' is PUBLIC and appears in plans/logs for audit. No rollback primitive — revert by re-applying captured config. confirm=True to execute. Use pbs_remote_get to inspect current config first.

PUT /config/remote/{name} Smoke-confirm: auth-id param name; whether partial PUT is accepted.

MUTATION (MEDIUM): remove a PBS remote and its stored credentials. Dry-run by default.

After deletion: any sync jobs referencing this remote break; re-add needs the password re-supplied. No rollback primitive — re-create with pbs_remote_create to recover. confirm=True to execute.

DELETE /config/remote/{name} Smoke-confirm: response shape on success.

MUTATION: create or update a PBS traffic-control (bandwidth-limit) rule. Dry-run by default.

Detects create-vs-update by reading the existing rule config (CAPTURE on update path): create → LOW: additive, no existing rule changed. update → MEDIUM: changing rate limits can throttle backups or saturate the network.

A too-low rate-in or rate-out throttles PBS backups to a crawl. No rollback primitive. confirm=True to execute. Use pbs_traffic_controls_list to see existing rules first, or pbs_traffic_control_delete to remove one.

POST (create) or PUT (update) /config/traffic-control[/{name}] Smoke-confirm: create-vs-update dispatch; rate-in/rate-out/burst-in/burst-out/timeframe param names.

MUTATION (MEDIUM): remove a PBS traffic-control (bandwidth-limit) rule. Dry-run by default.

After deletion: backups run unthrottled on the matched network. Recoverable by re-creating the rule with pbs_traffic_control_upsert. confirm=True to execute.

DELETE /config/traffic-control/{name} Smoke-confirm: response shape on success.

READ-ONLY: list available package updates (cached apt index) on a PBS node.

GET /nodes/{node}/apt/update. Smoke-confirm: shape not live-verified — expected per-package dicts (Package/Title/Description/Origin/Version/OldVersion/Priority/Section/Arch). Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs visibility only. To refresh this list first use pbs_apt_update_refresh. Needs PROXIMO_PBS_* config.

READ-ONLY: get a package's changelog text on a PBS node.

GET /nodes/{node}/apt/changelog?name=…[&version=…]. Smoke-confirm: shape not live-verified. The returned text is UPSTREAM/package-maintainer-authored (not Proxmox-authored) — classified ADVERSARIAL content (taint.ADVERSARIAL_TOOLS), like pve_apt_changelog and pmg_apt_changelog. Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs visibility only. Needs PROXIMO_PBS_* config.

READ-ONLY: get the current APT repository configuration of a PBS node.

GET /nodes/{node}/apt/repositories. Smoke-confirm: shape not live-verified — expected {files, errors, digest, infos, standard-repos}. files[].path + entry index are the coordinates pbs_apt_repository_set needs; standard-repos[].handle is what pbs_apt_repository_add needs. Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs visibility and repo config only. Needs PROXIMO_PBS_* config.

READ-ONLY: get installed versions of important Proxmox Backup Server packages on a PBS node.

GET /nodes/{node}/apt/versions. Smoke-confirm: shape not live-verified — expected per-package dicts (Package/Version/OldVersion + Arch/...). Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs visibility only. Needs PROXIMO_PBS_* config.

MUTATION: resynchronize the APT package index on a PBS node (apt-get update).

RISK_LOW: no package state change — refreshes the local index cache only. Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs visibility only — it does NOT install or upgrade any package. Idempotent — safe to re-run any time. Dry-run by default (returns a PLAN); confirm=True executes (POST, Smoke-confirm) and returns {"status": "submitted"|"ok", "result": <task UPID | None>}. Needs PROXIMO_PBS_* config.

MUTATION: enable/disable one APT repository entry on a PBS node, by file path + index.

RISK_MEDIUM: changes where packages come from — affects the NEXT upgrade's package provenance. CAPTURE: reads current repository state before planning (also readable directly via pbs_apt_repositories_get); if unreadable -> complete=False. Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs repo config only. Dry-run by default (returns a PLAN); confirm=True executes (POST, Smoke-confirm) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: add a standard repository to the configuration on a PBS node.

RISK_MEDIUM: adds a new package source — affects the NEXT upgrade's package provenance. CAPTURE: reads current repository state before planning (also readable directly via pbs_apt_repositories_get); if unreadable -> complete=False. No automatic revert: removing an added repository requires pbs_apt_repository_set to disable the resulting entry (there is no repository-delete endpoint). Proxmox's API deliberately does not expose upgrade execution; the upgrade itself happens at your console. This tool governs repo config only. Dry-run by default (returns a PLAN); confirm=True executes (PUT, Smoke-confirm) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

READ-ONLY: list all PBS users. Returns each user's userid, enabled flag, expiry, email, comment, and firstname/lastname; include_tokens=True also embeds token metadata (never secrets). Use pbs_user_get for one user's full config or pbs_user_tokens_list for a dedicated token listing. Needs PROXIMO_PBS_* config.

READ-ONLY: get a PBS user's config. Returns userid, enabled flag, expiry, email, comment, firstname/lastname (no tokens, no secrets). Use pbs_user_tokens_list for the user's API tokens, or pbs_user_create/update/delete to manage the user. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): create a PBS user. Dry-run by default.

PASSWORD REDACTION: password is OPTIONAL and, when supplied, a real credential — it is UNCONDITIONALLY redacted from the plan, detail, and audit ledger (only {"password": "[redacted]"} is recorded; omitted entirely when no password was given).

confirm=True executes and returns a dict; synchronous, no UPID. Use pbs_user_update to change it afterward, or pbs_user_delete to remove it. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update a PBS user (enable=False stops login immediately). Dry-run by default — the PLAN reads the user's current config first.

NOTE: this tool does NOT accept a password parameter — PBS's own PUT /access/users 'password' field is documented as ignored ("use PUT /access/password instead"); exposing a working-looking no-op parameter here would mislead a caller into thinking it changed the password.

confirm=True executes and returns a dict; synchronous, no UPID. Use pbs_user_get to see current state first, or pbs_user_delete to remove the user instead. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): delete a PBS user. Dry-run by default — the PLAN reads the user's current config and tokens to show what vanishes with it (permanent, no undo — any tokens owned by this user are removed with it, and ACL entries granted directly to this userid become orphaned). confirm=True executes and returns a dict; synchronous, no UPID. To disable login without deleting, use pbs_user_update (enable=False) instead. Needs PROXIMO_PBS_* config.

READ-ONLY: list API tokens for a PBS user. Returns each token's token-name, tokenid, comment, expiry, and enabled flag — NOT the secret (shown only once, at creation or regeneration). Use pbs_token_create/update/delete to manage tokens. Needs PROXIMO_PBS_* config.

READ-ONLY: get one PBS API token's metadata. Returns comment, expiry, enabled flag, token-name, and tokenid — NOT the secret. Use pbs_user_tokens_list to enumerate a user's tokens first. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): create an API token for a PBS user.

Dry-run by default. PBS has NO privsep concept (unlike PVE) — the new token has NO privileges until an ACL entry grants it some (pbs_acl_update with auth_id='{userid}!{token_name}'). confirm=True executes and returns a dict whose result carries the token secret (value) ONCE — it is never written to the audit ledger and cannot be retrieved again (only regenerated via pbs_token_update, which invalidates it). Synchronous. Use pbs_user_tokens_list to see a user's existing tokens, or pbs_token_delete to remove one. Needs PROXIMO_PBS_* config.

MUTATION: update a PBS API token's metadata. Dry-run by default.

RISK IS CONDITIONAL: regenerate=False is MEDIUM (metadata-only); regenerate=True is HIGH — it issues a brand-new secret and invalidates the OLD one IMMEDIATELY, with no grace period, breaking any integration still using it. When regenerate=True, confirm=True's result carries the NEW secret ONCE (key 'secret') — same never-in-ledger contract as pbs_token_create: the detail dict passed to the audit ledger never contains it.

confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM, IRREVERSIBLE): permanently revoke a PBS API token. Dry-run by default — the PLAN flags that revocation is permanent, the secret is gone forever, and any integration using it loses PBS API access immediately. confirm=True executes and returns a dict; synchronous, no UPID. Use pbs_user_tokens_list to see a user's tokens first, or pbs_token_create to issue a new one instead. Needs PROXIMO_PBS_* config.

READ-ONLY: list PBS ACL entries. Returns each entry's path, roleid, ugid (the user/token/group id), ugid_type ('user' or 'group'), and propagate flag. Use pbs_acl_update to grant/revoke, or pbs_roles_list to see PBS's fixed set of built-in roles. Needs PROXIMO_PBS_* config.

MUTATION (HIGH): grant or revoke a PBS ACL entry (PUT /access/acl) — this GRANTS or REVOKES AUTHORITY, so it is treated as HIGH risk unconditionally on this plane (PBS's ACL-inheritance/shadow semantics are not schema-documented or live-verified here, unlike PVE's plan_acl_modify which computes a shadow/widen preview — every change here is flagged HIGH rather than risk under-flagging one this module cannot yet analyze).

Dry-run by default (reads the current entries at this exact path for context). Exactly one of auth_id (a user or token principal) / group is required — PBS's PUT /access/acl carries a single 'role' (not PVE's comma-separated multi-role list) and folds user+token identity into one 'auth-id' field. delete=False = grant; delete=True = revoke. confirm=True executes and returns a dict; synchronous, no UPID. Use pbs_acl_get to see current entries or pbs_roles_list to see PBS's fixed set of built-in roles. Needs PROXIMO_PBS_* config.

READ-ONLY: list PBS's built-in roles. Returns each role's id, privilege list, and comment. PBS roles are a FIXED enum (Admin, Audit, NoAccess, Datastore*/Remote*/Tape* roles) — unlike PVE, there is no create/update/delete endpoint for PBS roles. Use pbs_acl_update to assign a role to a principal. Needs PROXIMO_PBS_* config.

READ-ONLY: resolve effective privileges for a PBS user/token. Returns a map of ACL path to a map of privilege name to propagate-bit — the RESOLVED (inherited + direct) view, unlike pbs_acl_get's raw entry list. Use pbs_acl_get to see the raw ACL entries this resolves from. Needs PROXIMO_PBS_* config.

READ-ONLY: list configured AD realms. Use pbs_realm_ad_get for one realm's full config. Needs PROXIMO_PBS_* config.

READ-ONLY: get one AD realm's config. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): create an AD authentication realm. Dry-run by default.

PASSWORD REDACTION: password (the AD bind password), when supplied, is UNCONDITIONALLY redacted from the plan, detail, and audit ledger (only {"password": "[redacted]"} is recorded). confirm=True executes and returns a dict; synchronous, no UPID. Use pbs_realm_ad_update to change it afterward, or pbs_realm_ad_delete to remove it. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update an AD realm's config. Dry-run by default — the PLAN reads the realm's current config first. password, if supplied, is redacted identically to pbs_realm_ad_create's. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): permanently delete an AD realm. Dry-run by default — the PLAN reads the realm's current config and flags that any users authenticating via it lose login access. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: list configured LDAP realms. Use pbs_realm_ldap_get for one realm's full config. Needs PROXIMO_PBS_* config.

READ-ONLY: get one LDAP realm's config. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): create an LDAP authentication realm. Dry-run by default. base_dn and user_attr are REQUIRED (unlike AD, which needs neither on create).

PASSWORD REDACTION: password is UNCONDITIONALLY redacted identically to pbs_realm_ad_create's. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update an LDAP realm's config. Dry-run by default — the PLAN reads the realm's current config first. password, if supplied, is redacted identically to pbs_realm_ldap_create's. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): permanently delete an LDAP realm. Dry-run by default — the PLAN reads the realm's current config and flags that any users authenticating via it lose login access. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: list configured OpenID realms. Use pbs_realm_openid_get for one realm's full config. Needs PROXIMO_PBS_* config.

READ-ONLY: get one OpenID realm's config (never includes client_key). Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): create an OpenID authentication realm. Dry-run by default.

CLIENT-KEY REDACTION: client_key (the OAuth client secret), when supplied, is UNCONDITIONALLY redacted from the plan, detail, and audit ledger (only {"client-key": "[redacted]"} is recorded). confirm=True executes and returns a dict; synchronous, no UPID. NOTE: the browser-based auth-url/login handshake is out of scope for this plane (token-auth-shaped tools only) — see module docstring. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update an OpenID realm's config. Dry-run by default — the PLAN reads the realm's current config first. client_key, if supplied, is redacted identically to pbs_realm_openid_create's. confirm=True executes and returns a dict; synchronous, no UPID.

NOTE: there is NO username_claim parameter here — the live PBS schema makes it create-only (set it at pbs_realm_openid_create time); PUT is additionalProperties:false, so accepting it here would only hard-fail the whole update server-side. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): permanently delete an OpenID realm. Dry-run by default — the PLAN reads the realm's current config and flags that any users authenticating via it lose login access. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: get the built-in PAM realm's config (comment/default only). Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update the built-in PAM realm's comment/default-preselect flag. Dry-run by default. PAM has NO delete endpoint — the worst case here is a comment/default change, not a lockout. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: get the built-in PBS-auth realm's config (comment/default only). Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update the built-in PBS-auth realm's comment/default-preselect flag. Dry-run by default. This realm has NO delete endpoint — the worst case here is a comment/default change, not a lockout. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: list ALL users' TFA configuration (per-user entries + lock state). Use pbs_tfa_user_get to scope to one user. Needs PROXIMO_PBS_* config.

READ-ONLY: list one user's TFA entries. Needs PROXIMO_PBS_* config.

READ-ONLY: get one TFA entry. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): add a TFA entry for a user. Dry-run by default.

SECRET-BEARING RESPONSE for type='recovery': confirm=True's result carries {"recovery": [], ...} — SERVER-GENERATED secret material, shown ONCE and never retrievable again. It is never written to the audit ledger (the detail= dict below never includes 'recovery'/'challenge'/'id'). password, if supplied, is UNCONDITIONALLY redacted identically to pbs_user_create's. For type='totp', the caller supplies the secret (via totp) — PBS does not generate one server-side for that type. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update a TFA entry's description/enabled flag. Dry-run by default — the PLAN reads the current entry first. password, if supplied, is redacted identically to pbs_tfa_add's. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (HIGH, IRREVERSIBLE): permanently remove one TFA factor from a user. HIGH because it WEAKENS authentication — an account-takeover enabler, and a lockout if it's the user's last factor on a TFA-required realm. Dry-run by default — the PLAN flags the permanence and the takeover/lockout risk. password, if supplied, is redacted identically to pbs_tfa_add's. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

MUTATION (HIGH): clear a user's TOTP lockout (PUT /access/users/{userid}/unlock-tfa — note the path lives under /access/users/, not /access/tfa/{userid}/). HIGH because it removes the anti-brute-force throttle guarding a 6-digit TOTP keyspace — an account-takeover enabler if the lockout was triggered by a real guessing attack. Dry-run by default. confirm=True executes and returns a dict whose result is a bool: whether the user was previously locked out. Synchronous. Needs PROXIMO_PBS_* config.

READ-ONLY: get the server-wide WebAuthn relying-party config (id/origin/rp/ allow-subdomains). Needs PROXIMO_PBS_* config.

MUTATION (MEDIUM): update the server-wide WebAuthn config. Dry-run by default — the PLAN reads the current config and calls out that changing rp_id WILL break every existing WebAuthn credential on the server, and origin MAY. confirm=True executes and returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.

READ-ONLY: list registered PBS ACME account NAMES (the schema's own response item is {"name": str} only — use pbs_acme_account_get for full account detail). Needs PROXIMO_PBS_* config.

READ-ONLY: get one PBS ACME account's full config (account/directory/location/tos). Does NOT include eab_hmac_key — PBS never returns it on read. Needs PROXIMO_PBS_* config.

READ-ONLY: list PBS's built-in catalog of known ACME CA directory endpoints (name + URL pairs, e.g. Let's Encrypt production/staging). No params. Needs PROXIMO_PBS_* config.

READ-ONLY: get the Terms-of-Service URL for an ACME directory (or None if the CA advertises no ToS). The PBS host fetches the given directory URL live (https-only, validated) and the response is authored by whoever controls that URL — classified ADVERSARIAL in the taint control for exactly that reason. Needs PROXIMO_PBS_* config.

READ-ONLY: list the catalog of known ACME challenge plugin types (id/name/schema/type per entry) — the parameter schema each plugin type+data pairing must satisfy. No params. Needs PROXIMO_PBS_* config.

READ-ONLY: list all configured PBS ACME DNS challenge plugins, INCLUDING the raw data credential blob for each (PBS does not strip it on read). Handle the result as sensitive. Needs PROXIMO_PBS_* config.

READ-ONLY: get one PBS ACME plugin's full config, INCLUDING the raw data credential blob (PBS does not strip it on read). Handle the result as sensitive. Needs PROXIMO_PBS_* config.

MUTATION: register a new ACME account with the CA. Dry-run by default.

Additive — does not affect any existing account. Pair with pbs_acme_plugin_create (DNS-01 challenge), then pbs_acme_cert_order, to actually issue a cert; to remove an account instead use pbs_acme_account_delete. confirm=True executes (POST /config/acme/account, synchronous — PBS returns null) and returns {"status": "ok", "result": None}; the default returns a dry-run PLAN dict. Needs PROXIMO_PBS_* config.

MUTATION: update ACME account contact info. Dry-run by default.

LOW risk — metadata update only, no cert impact. PBS's PUT accepts ONLY contact (no eab/tos fields on update — those are create-only). To delete the account instead use pbs_acme_account_delete. confirm=True executes (synchronous — PBS returns null) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: IRREVERSIBLE — DEACTIVATES an ACME account at the CA (not just local config removal) and deletes the local record. Dry-run by default.

HIGH risk: TLS lockout at cert expiry if this is the only account. The account key is destroyed — registering again with pbs_acme_account_create creates a DIFFERENT CA account, not a restore of this one. force=delete local data even if the CA refuses to deactivate (PBS-only escape hatch; PVE's equivalent tool has no such flag). The dry-run PLAN captures the current config as evidence only. confirm=True executes (synchronous — PBS returns null) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: create an ACME DNS challenge plugin. Dry-run by default.

Additive — does not affect any existing plugin. dns_api = DNS provider name (e.g. 'cf', 'route53'). Reference plugin_id when ordering a cert via a DNS-01 challenge; to remove the plugin use pbs_acme_plugin_delete. confirm=True executes (POST /config/acme/plugins, synchronous — PBS returns null) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: update an ACME DNS challenge plugin. Dry-run by default.

MEDIUM risk — invalid new credentials break cert renewal for every domain using this plugin at the next attempt. To remove a plugin instead use pbs_acme_plugin_delete. The dry-run PLAN includes the plugin's current config with the credential blob redacted (PBS DOES return it on read — see module docstring); confirm=True executes (PUT /config/acme/plugins/{id}, synchronous — PBS returns null) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: delete an ACME DNS challenge plugin. Dry-run by default.

HIGH risk: cert auto-renewal breaks for every domain using this plugin — TLS lockout at cert expiry unless a fallback challenge method is configured. No UNDO primitive — recreate with pbs_acme_plugin_create, but the credentials must be re-supplied by the caller. The dry-run PLAN captures the current config (credential redacted) as evidence only; confirm=True executes (synchronous — PBS returns null) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: order a NEW ACME TLS certificate for a PBS node. Dry-run by default.

MEDIUM (mirrors pve_acme_cert_order's rating): the cert is CA-validated and installed ONLY on a successful challenge — a failed challenge leaves the existing cert untouched. PBS's schema declares a null return (unlike PVE's task UPID) — this does NOT mean issuance is synchronous; the ACME challenge round-trip with the CA still happens on the PBS side after this call returns, and there is nothing to poll here (no UPID exists to wait on). PBS has NO ACME cert revoke (unlike PVE). force=overwrite existing files. confirm=True executes (POST /nodes/{node}/certificates/acme/certificate) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

MUTATION: renew the existing ACME TLS certificate for a PBS node. Dry-run by default.

MEDIUM (mirrors pve_acme_cert_renew's rating): CA-validated, installed only on success (a failure can't lock you out). Same null-return honesty as pbs_acme_cert_order — PBS declares no return value for this call, but the renewal itself still completes asynchronously on the PBS side; there is no UPID to poll. force=renew even if not yet within the renewal lead time. PBS has NO ACME cert revoke. confirm=True executes (PUT /nodes/{node}/certificates/acme/ certificate) and returns {"status": "ok", "result": None}. Needs PROXIMO_PBS_* config.

READ-ONLY: job-level view of GC (garbage collection) jobs, max one per datastore, across ALL datastores unless store filters to one. Distinct from the existing per-datastore pbs_gc_status (single-store detail only, no schedule/next-run fields). SCHEMA-CHECKED (not inferred): GET /admin/gc/{store} also exists on the live schema and is the path-segment ALIAS of this same store filter — byte-identical description and returns shape, store still marked optional in the path form; this tool's store param covers it (see proximo.pbs_admin module docstring fact #1). REVIEWED_TRUSTED. Needs PROXIMO_PBS_* config.

READ-ONLY: job-level view of prune jobs. REVIEWED_TRUSTED (job comment/schedule, matches pbs_jobs_list precedent). Use pbs_job_run(job_type='prune', ...) to trigger one manually. Needs PROXIMO_PBS_* config.

READ-ONLY: job-level view of sync jobs. REVIEWED_TRUSTED. Use pbs_job_run(job_type='sync', ...) to trigger one manually. Needs PROXIMO_PBS_* config.

READ-ONLY: job-level view of verification jobs. REVIEWED_TRUSTED. Use pbs_job_run(job_type='verify', ...) to trigger one manually. Needs PROXIMO_PBS_* config.