imago

Praetor manages this repository's declared governance policy. This managed block records adoption state; it is not a verification certificate.

Verification: make verify-all runs the repository's configured verification cascade.

HISS Audit: praetorctl audit enforces policy, generated-surface integrity, and the debt ratchet.

Context Sync: praetorctl compile-context --verify verifies every generated agent context against AGENTS.md.

Documentation: make docs-lint enforces locked Markdown style and the private scratch-link policy.

Debt Baseline: .standards-baseline.json anchors the debt ratchet at 0 recorded infractions; audit forbids growth.

Enterprise-grade, hardened, hardware-accelerated cloud and bare-metal OS image forge with pre-baked runtimes.

Fleet identity: this repository is cordanaLLM/imago (formerly lusoris/lusoris-cloud-images), the reusable image builder named in the Aegis-OS connected stack contract; its kernel forge is cordanaLLM/nucleus. Governance, golusoris adoption and the remaining migration steps are tracked in the routed planning graph (see ADR-0019).

📖 Documentation Portal  •  📋 Complete Flavor Catalog (44 Flavors)  •  📐 Architecture & Principles  •  🔒 Security Advisories

---

Why imago?

Stock cloud distributions waste minutes downloading gigabytes of kernel modules, GPU drivers, and container runtimes on first boot. imago bakes these dependencies into production-ready, verified images (.qcow2, .raw, .vmdk, and Proxmox/Unraid/VMware templates).

• Zero Base Bloat: Complete elimination of Canonical snaps, telemetry services (ubuntu-pro-client, landscape-common, popularity-contest), motd news, and unneeded documentation.
• Single Source of Truth (versions.json): Every upstream URL, driver branch, and container tag originates from a single declarative manifest validated against versions.schema.json.
• Multi-Generational Hardware: Tailored driver stacks for Intel Arc/Flex/Xe2, AMD Mesa/ROCm 7.2, and NVIDIA generational CUDA (Pascal 580, Ampere/Ada 595, Hopper/Blackwell 615).
• Hypervisor & Bare-Metal Speed Engine: Coexisting qemu-guest-agent + open-vm-tools, Unraid virtiofs/9p host sharing, fast-boot NoCloud discovery (< 2s), ZRAM compressed swap guard, weekly fstrim.timer, and VirtIO mq-deadline I/O scheduling.
• Multi-Distribution Upstream Roadmap: Standardized on Ubuntu 26.04/24.04 LTS for accelerator-rich workloads, with an active architectural roadmap (ADR-0009) targeting Debian Bookworm/Trixie for lean microVMs and storage appliances, and Alpine for ultra-lean edge gateways.
• Resilient Global Time: Cryptographically authenticated Network Time Security (NTS RFC 8915) combining Cloudflare Anycast and European national metrology laboratories (PTB, Netnod, SIDN, 3eck).

---

Build Architecture

flowchart TD
    %% Semantic class definitions with vibrant, high-contrast jewel palettes
    classDef ssot fill:#0284c7,stroke:#0369a1,stroke-width:2px,color:#ffffff
    classDef foundation fill:#d97706,stroke:#b45309,stroke-width:2px,color:#ffffff
    classDef packer fill:#7c3aed,stroke:#6d28d9,stroke-width:2px,color:#ffffff
    classDef imageless fill:#059669,stroke:#047857,stroke-width:2px,color:#ffffff
    classDef tiers fill:#e11d48,stroke:#be123c,stroke-width:2px,color:#ffffff
    classDef artifacts fill:#4338ca,stroke:#3730a3,stroke-width:2px,color:#ffffff

    subgraph SSOT["Declarative Source of Truth & Upstream Matrix"]
        SRC["Upstream Base OS Matrix<br/><small>Ubuntu LTS Core · Debian · Alpine Roadmap</small>"]:::ssot
        BOM[("versions.json<br/><small>Pinned Upstream BOM & SSOT</small>")]:::ssot
    end

    subgraph Foundation["Hardened Foundation Pipeline (Stages 00–25)"]
        S0["00-base-strip<br/><small>Purge snapd & telemetry</small>"]:::foundation
        S1["05-hypervisor<br/><small>QEMU + VMware + VirtFS</small>"]:::foundation
        S2["10-time<br/><small>Multi-peer Anycast NTS</small>"]:::foundation
        S3["20-sysctl<br/><small>CIS Baseline & BBR</small>"]:::foundation
        S4["25-baremetal<br/><small>NVMe mq-deadline & ZRAM</small>"]:::foundation
        S0 --> S1 --> S2 --> S3 --> S4
    end

    subgraph DualPath["Dual Build & Provisioning Engine"]
        direction TB
        subgraph TrackPacker["Track A: Packer Image Factory"]
            PE["Packer Engine<br/><small>QEMU / Proxmox VE</small>"]:::packer
            Tiers["44 Production Flavors<br/><small>7 Workload Tiers × Hardware Matrix</small>"]:::tiers
            Artifacts[".qcow2.zst · .raw.zst · .vmdk.zst<br/><small>High-Ratio Zstandard Artifacts</small>"]:::artifacts
            PE --> Tiers
            Tiers --> Artifacts
        end
        subgraph TrackImageless["Track B: Imageless & MicroVMs"]
            CLI["imago CLI / MCP<br/><small>Go 1.27 Engine</small>"]:::imageless
            Apply["In-Place Provisioning<br/><small>SSH / Local Host Apply</small>"]:::imageless
            Boot["MicroVM Direct Kernel Boot<br/><small>Cloud-Hypervisor & Firecracker</small>"]:::imageless
            CLI --> Apply
            CLI --> Boot
        end
    end

    SSOT --> Foundation
    Foundation --> PE
    Foundation -.-> CLI

    style SSOT fill:none,stroke:#0284c7,stroke-width:2px,stroke-dasharray: 4 4
    style Foundation fill:none,stroke:#d97706,stroke-width:2px,stroke-dasharray: 4 4
    style TrackPacker fill:none,stroke:#7c3aed,stroke-width:2px,stroke-dasharray: 4 4
    style TrackImageless fill:none,stroke:#059669,stroke-width:2px,stroke-dasharray: 4 4
    style DualPath fill:none,stroke:#64748b,stroke-width:2px

Loading

---

Workload Tier Summary (44 Flavors)

To keep maintenance low and usability high, flavors are partitioned into 7 distinct tiers.

A published release and the weekly schedule build base-generic, docker-generic and k8s-node-generic; every other flavor builds on a manual run of release-matrix.yml with its flavor input (or locally, see Quickstart).

Tier	Flavors	Hardware Acceleration	Key Runtime Components	Documentation
1. Base Cloud	8	Generic, Intel Xe, AMD Mesa, NVIDIA (580 to 615)	Hardened OS, Anycast NTS, enroot (datacenter), QEMU/VMware agents	📖 Base Guide
2. Container Hosts	7	Generic, Intel QuickSync, AMD ROCm, NVIDIA CDI	Docker CE 29.8, Docker Compose v2, Podman 5.x	📖 Containers Guide
3. Enterprise K8s	9	Generic, Intel Arc, AMD ROCm 7.2, NVIDIA Mainstream/Bleeding	containerd 2.3.5, kubelet 1.37.0, stargz-snapshotter (opt-in), Cilium/Calico preheat	📖 Kubernetes Guide
4. K3s Edge Fleet	5	Generic, Intel QuickSync, AMD ROCm 7.2, NVIDIA CDI	Lightweight K3s (< 300MB RAM), Flannel, SQLite	📖 K3s Guide
5. CloudNative & Storage	4	Generic, Baremetal, NVMe-oF, OpenZFS 2.3	Read-only root immutability, OpenZFS, CloudNativePG	📖 CloudNative Guide
6. AI & LLM Inference	6	AMX/AVX-512, Intel Xe2, AMD ROCm 7.2, NVIDIA (595/615)	Transparent Hugepages, NUMA, stargz-snapshotter (opt-in), enroot (NVIDIA), vLLM / Ollama	📖 AI Inference Guide
7. Homelab Appliances	5	Coral TPU, QuickSync, Dual VA-API, ARM64 binfmt, i386	Frigate NVR, AdGuard/Pi-hole, Jellyfin, CI runner, SteamCMD	📖 Homelab Guide

📋 Detailed Specifications: Browse the complete list of all 44 target configurations in FLAVORS.md or explore them interactively in the Documentation Portal Matrix.

---

Quickstart

Prerequisites

• Packer $\ge$ 1.9.0
• QEMU with KVM support (qemu-system-x86_64)
• ShellCheck, Shfmt, and Yamllint
• Codespell and Ruff at the versions of the lint lock: pip install --require-hashes -r .github/requirements/lint.txt

Build Locally (Standalone QEMU)

# Clone the repository
git clone https://github.com/cordanaLLM/imago.git
cd imago

# Initialize plugins and run quality gates
make init
make lint
make test

# Build images (or specify any flavor from FLAVORS.md)
make build-base-generic        # Minimal hardened OS
make build-docker-nvidia       # Docker CE + NVIDIA 595 Container Toolkit
make build-k8s-cilium          # Enterprise K8s + preheated Cilium
make build-k3s-agent-generic   # Lightweight Edge K3s worker (< 300MB RAM)
make build-cloudnative-generic # Immutable container host (read-only root)
make build-cloudnative-storage # CNCF storage appliance (NVMe-oF / ZFS)
make build-ai-infer-nvidia     # AI inference appliance (vLLM / NUMA tuning)

The imago build --backend local CLI also executes Packer after checking the installed toolchain pins from versions.json, then reports the run log, QCOW2 path and SHA256. Other backends refuse execution; --dry-run validates plans for every backend. See local build flags and evidence.

MCP tools returning JSON provide structuredContent and matching compact JSON text through the Go SDK; tool errors preserve their message in isError: true results. See MCP tool contracts.

---

Repository & Documentation Map

.
├── versions.json              # Single Source of Truth (SSOT) for all versions
├── versions.schema.json       # JSON Schema (Draft 2020-12) validating SSOT
├── FLAVORS.md                 # Segmented catalog of all 44 production flavors & make targets
├── mkdocs.yml                 # Documentation portal configuration
├── docs/                      # Comprehensive engineering documentation
│   ├── flavors/               # Detailed guides for each workload tier
│   ├── platforms/             # Hypervisors: Proxmox, Unraid, VMware, Bare-Metal
│   ├── hardware/              # Acceleration: NVIDIA CUDA, Intel Arc, AMD ROCm
│   ├── security/              # CIS Benchmarks, Anycast NTS, Supply Chain
│   ├── adr/                   # Architecture Decision Records (0001–0011)
│   └── community/             # Contributing, Security, Audits, Governance
├── packer/                    # Modular Packer HCL2 templates & shell provisioners
├── tests/                     # Automated pytest verification suite
└── Makefile                   # Unified local targets (lint, test, build-*)

---

Governance & Security

• Security Advisories: To report security vulnerabilities, open a GitHub Private Security Advisory.
• Engineering Principles: All changes must satisfy Engineering Principles and Rule Crosswalk.
• License: EUPL-1.2 — Copyright © 2026 The Lusoris Authors. The License section says from which revision on.

License

imago is licensed under the European Union Public Licence 1.2 (EUPL-1.2).

• From which revision on: every revision after commit 44a6bfa is EUPL-1.2, and so is every release.
• Earlier revisions: every revision up to and including 44a6bfa was published under Apache-2.0 and stays available under it. No release was tagged in that time, and the repository carried no NOTICE file.
• Per-file information: REUSE.toml names the licence and the copyright holder of every file, and LICENSES/ holds each licence text. Bundled third-party files keep their MIT licence.

ADR-0023 records the decision.