README
ΒΆ
βοΈ MagosDominus (a.k.a. Magos)
βThe Machine does not err. The flesh errs. The Code is truth, and I am its voice.β β Credus del Adeptus Mechanicus
π About
MagosDominus is a lightweight GitOps agent forged in the spirit of the Adeptus Mechanicus. Its sole purpose: to enforce the declared state from your sacred repository (Git) and reconcile it with the material reality of your homelab.
Unlike the bloated rites of Kubernetes and endless CRDs, MagosDominus imposes order directly on a simple Linux server with Podman Compose. No unnecessary ceremony, no wasted bureaucracy β only obedience to the written mandate.
Each reconciliation loop is a ritual. Each deployment, a litany. Where drift appears, corruption is purged. Where the manifest and the machine diverge, the Magos enforces the will of the Code.
βΈ»
β¨ Features (planned)
β’ Registry watcher (GHCR first, later DockerHub/Quay).
β’ ImagePolicy evaluation:
β’ Semantic version ranges (>=1.2.0 <2.0.0)
β’ Regex filters on tags
β’ Architecture constraints (e.g. amd64)
β’ Min age delays to avoid race conditions
β’ (Optional) Signature verification with cosign
β’ (Optional) Vulnerability scanning (Trivy)
β’ GitOps reconciler:
β’ Patches Compose files with immutable digests (@sha256:...)
β’ Commits and pushes via GitHub App (no long-lived tokens)
β’ Direct push to main or PR workflow
β’ Optional applier:
β’ Decrypts secrets with SOPS
β’ Runs podman-compose pull && up -d for the affected stack
β’ State & observability:
β’ Minimal local cache (last digest applied)
β’ Structured logs
β’ /healthz and /metrics endpoint (future)
π Repository layout
cmd/server/ # entrypoint internal/cli/ # command-line interface internal/watcher/ # registry polling & events internal/daemon/ # reconciliation loop
π Config basics .env file
- MD_REPO = env variable with the path to your GitOps repo.
Image policy
Add a comment in your compose file, just after the image line, like so:
-
Policy Semver image: ...image:0.0.1 # {"magos": {"policy": "semver", "repo": "repoUrl"}}
-
Policy Latest image: ...image:latest # {"magos": {"policy": "latest", "repo": "repoUrl"}}
-
Policy Digest image: ...image@sha256:abcd1234 # {"magos": {"policy": "digest", "repo": "repoUrl"}}
- JSON comment should start with # {"magos"
- MagosDominus ignores comments that do not start with # {"magos"
- The field "policy" defines the policy to be enforced
- Reconciliation only replaces or with the latest matching tag or digest.
π How it works
1. Watcher detects a new image in GHCR.
2. Policy evaluator checks if it matches semver, arch, signature, etc.
3. If approved, Reconciler patches the GitOps repo (image: β digest), commits, and pushes with a GitHub App identity.
4. Loop or Applier on the homelab pulls the repo, decrypts secrets, and redeploys the stack.
βΈ»
π Security
β’ Uses a GitHub App for ephemeral push tokens.
β’ Branch protection recommended on main.
β’ Secrets encrypted with SOPS + age, never stored in plain Git.
β’ Images pinned by digest in GitOps.
β’ Optional: cosign for signature verification.
βΈ»
π οΈ Roadmap
β’ MVP: GHCR polling β semver policy β patch Compose β push to main
β’ Add minAge & arch constraints
β’ Applier: SOPS decrypt + podman-compose
β’ PR mode instead of push
β’ Cosign signature verification
β’ Trivy vulnerability checks
β’ /healthz + /metrics
βΈ»
π License
MIT.
Directories