netbox-proxbox: Instructions file for Codex

netbox-proxbox Agent Guide

CLAUDE.md is the source repository guide. Read and follow it before making changes in this repository.

The EdgeUno repository and vendor checkout are read-only reference sources; never edit or target them. Disabled endpoints are a hard no-network gate. Console authentication, tickets, upstream URLs, secrets, and TLS decisions stay server-side. The semantic bridge exposes only its documented typed manifest, not a raw proxy. Proxbox, NetBox, and public companion plugins each own their respective configuration and credential state.

CLAUDE.md is canonical. This wrapper repeats the safety and current-state facts that an agent must have even when @CLAUDE.md expansion is unavailable:

• Keep changes inside the canonical Emerson repository. Never target EdgeUno.
• Preserve the public boundary and run python scripts/check_public_boundary.py.
• The private PBS matrix checkout uses COMPANION_READ_SSH_KEY, an encrypted Actions secret containing a read-only deploy key for emersonfelipesp/netbox-pbs only. Keep credential persistence disabled and keep the private key out of tests, logs, and artifacts.
• Scan built wheel and source archives with --artifact; the reviewed manifest covers name, domain, URL, command, path, package, service, distribution, workspace, retired contract, and private host identifiers; inspection failures are fatal.
• Keep the persisted nmulticloud InfluxDB organization default unchanged; it is public configuration and changing it requires a separately scoped additive compatibility migration.
• Treat disabled endpoints as a hard no-network gate.
• Keep credentials, console tickets, upstream URLs, and TLS decisions server-side and out of browser-readable output.
• Keep companion-plugin imports optional and lazy; enabled-but-broken companions fail at startup rather than degrading silently.
• netbox-pbs owns PBS REST sync, managed PBS configuration, token secrets, and audited actions. A linked PBSEndpoint is inventory only and never receives its token. PBS deployment, Proxmox storage registration, and VM backups use proxbox-api for the Proxmox operations; see docs/companion-plugins/netbox-pbs.md.
• netbox-openbao is optional. Automatic credential storage selects OpenBao only when the companion is enabled and otherwise selects local Fernet storage; explicit selections never fall back.
• Keep Proxmox endpoint API readiness response-local: derive serialized service monitoring eligibility from non-secret endpoint metadata plus response-local SSH and RPC readiness, preserve the guarded netbox-rpc model import before endpoint overrides, read each required global setting at most once per serializer, and derive OpenBao SSH readiness from one list-wide, actor- authorized credential metadata query without resolving credential material.
• Keep historical migrations immutable and add a migration for schema changes.
• Keep automatic_background_tasks strictly boolean and default-enabled. Disabled startup discovery and system-monitor scheduling must preserve explicit user jobs, integrity handlers, models, migrations, and audit records. Drain only the stock unowned, unscoped one-minute monitor; restart all application and worker processes for configuration changes.
• Keep ProxboxPluginSettings.sync_job_timeout UI-backed and bounded to 3600–604800 seconds. Resolve it when enqueueing a sync job, preserve explicit per-enqueue overrides, and never mutate the timeout of an already-running job.
• Keep Dockerfile.oci testing-only, preserve its separate NetBox and proxbox-api Python runtimes, and keep its OCI entrypoint equivalent to the Proxmox LXC /sbin/init path. Release builds must use the single plugin/backend pairing declared in COMPATIBILITY.md only after both required PyPI APIs expose compatible, non-yanked source distributions or pure-Python universal wheels, smoke-test the amd64 manifest from the final multi-architecture index, and publish that same digest without rebuilding.
• Convert exact Data Protection schedules through the source endpoint's discovered IANA timezone; keep unresolved timing visibly approximate and cap combined calendar node selection at 50.
• Keep home dashboard badge and card hydration on one bounded four-worker pool; route initial requests and at most three coalesced retries per card through that pool, keep successful badge state independent from card errors, and render backend capacity responses as throttled rather than failed. Treat the Proxmox push cache as a hint and verify the cached backend endpoint identity before use.
• Keep the cluster Virtual Machines tab's selected-row Delete action routed to NetBox's core VirtualMachine bulk-delete endpoint. Never route selected VM IDs to the parent cluster delete action; preserve the version-checked action adapter and its real-Django regression.
• Keep per-VM HA reads endpoint-exact. The VM sync-state endpoint is authoritative; linked typed cluster and node rows must agree with it. The tab intersects that exact enabled endpoint with caller visibility. The REST route requires virtual_machine_id={netbox_vm_pk}, restricts the VM by object permission, verifies its synchronized VM ID matches the path vmid, and queries only that one enabled, visible endpoint. Invalid, unresolved, or hidden identity must fail before backend I/O.
• Update MkDocs sources, this wrapper, CLAUDE.md, and generated llms.txt together when architecture or operator behavior changes.
• Run focused tests, mkdocs build --strict, the public-boundary scanner, and a per-function complexity audit when executable source changes.