Newer
Older
gnexus-book / 10-systems / applications / gnexus-book.md

owner: gmikcon status: active last_reviewed: 2026-09-24 review_interval: 30d confidence: high

source_of_truth: ssh-host-verified

Gnexus Book

Gnexus Book is the canonical infrastructure knowledge base and maintenance API for the personal digital and server infrastructure.

Deployment

  • Runs as KVM VM gnbook (192.168.1.170) on hypervisor hp-proliant-dl380-g6 (192.168.1.130).
  • SSH: ubuntu on 192.168.1.170 (credentials in gnexus-creds, secret gnauth-gnbook-ssh).
  • Repository path: /home/ubuntu/gnexus-book (branch master).
  • Source of truth: Markdown, YAML inventory, JSON Schema, and Git history.

Runtime Components

  • Backend: FastAPI under server/.
  • Agent interface: MCP server under server/app/mcp_server.py.
  • UI: Vue/Vite under ui/.
  • UI dependency: gnexus-ui-kit.

Endpoints

  • REST API: http://192.168.1.170:8000/ (uvicorn, openapi at /openapi.json).
  • MCP (SSE): http://192.168.1.170:8001/sse.
  • UI (LAN): http://192.168.1.170:80/ (nginx serves the built SPA).
  • Services run as user-level systemd units under user@1000.service: gnexus-book-backend.service (uvicorn :8000) and gnexus-book-mcp.service (MCP server).

Maintenance Model

Agents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API.

Pending-change queue lives in 90-maintenance/pending-changes/ (untracked JSON files; 11 older ones are git-tracked). Repository-wide validation scans every pending JSON, so a single invalid pending file blocks all applies and commits.

Poisoned-pending protection (since 2026-09-24, commit c77bcb1):

  • Create (propose_doc_change, propose_inventory_item_change, update_doc): payloads with secret patterns or unsafe doc targets (outside repo root) are rejected BEFORE any file is written — a rejected request leaves no pending file behind.
  • Apply: on validation failure the target file is rolled back AND the change's own pending JSON is removed (full rollback, both doc and inventory-item paths).
  • delete_pending_change (MCP) / DELETE /changes/{id} (REST): deletes pending or corrupt records; applied records are refused (409).
  • list_pending_changes tolerates corrupt JSON files and reports them with status corrupt; corrupt records can be deleted but not applied.
  • update_doc cleans up its own pending JSON automatically if apply or commit fails.

For agent-facing MCP usage rules, see ../../90-maintenance/agent-mcp-usage.md.

No raw credentials are documented here.