Concepts and architecture
Concepts
Section titled “Concepts”- Asset: any inventory item: a server, a Proxmox CT or VM, a container, a Docker image, network or volume, a domain… Assets are related to each other (a container runs on a server, a domain reaches a service) and form the topology view.
- Enrolment: the step that turns a server into an inventoried node. A single-use token downloads a script that creates an inventory user with a minimal, read-only
sudoersand pins the host key fingerprints. - Discovery and collection: the worker connects over SSH, gathers facts with Ansible and recursively discovers what each node contains.
- Reconciliation: the inventory is periodically compared with reality. New items are added, changes are updated and whatever disappears is retired after several passes without seeing it.
- SBOMs and findings: every image, server or CT has a CycloneDX SBOM. SBOMs are re-evaluated against the latest Trivy database without reconnecting to the machines.
- Projects, tags and policies: group assets, control the reconciliation interval and define who may open a terminal on what.
Services
Section titled “Services”| Service | Technology | Role |
|---|---|---|
web |
Angular, served by nginx | User interface; forwards /api/ to the API |
api |
NestJS + Fastify + TypeORM | REST with OpenAPI, authentication and server enrolment; runs migrations on start-up |
worker |
NestJS + Ansible + Trivy | Collection, discovery, scanning and reconciliation; consumes the queues and scales to several replicas |
gateway |
The worker image in gateway mode |
Interactive terminal (WebSocket → SSH with PTY); no queues and no access to secrets |
| PostgreSQL 18 | Inventory, SBOMs, findings and audit log | |
| Redis 7 | Job queue (BullMQ) | |
| OpenBao | Optional | Secrets provider and SSH CA |
The API never runs Ansible or Trivy: all heavy work goes through the queue to the worker.
Secrets
Section titled “Secrets”The database only stores secret://… references. The values live in:
- OpenBao (recommended): KV v2 for secrets and an SSH CA that signs short-lived certificates, so servers are enrolled without per-server keys.
- Local provider: secrets encrypted with AES-256-GCM using a master key kept outside the database.
The credential vault (passwords used by people, such as consoles or IPMI) lives in a separate store with its own identity. Only the API can read it; the worker cannot.
Worker scaling
Section titled “Worker scaling”Several worker replicas can run at once. Jobs are distributed through per-type queues without duplication, with a limit on concurrent jobs per server (a CT counts against its node) and coordination through locks and a leader in Redis. If a replica dies, another one picks up its jobs.
Web terminal
Section titled “Web terminal”The gateway opens the SSH session with the server’s administration account using a certificate signed by the API that lasts a few minutes. It is only available on servers with administration access enabled, and permissions are granted per asset, tag or project.