{"id":36454625,"url":"https://github.com/jpvargasdev/magos-dominus","last_synced_at":"2026-04-01T18:34:06.414Z","repository":{"id":317481650,"uuid":"1067591577","full_name":"jpvargasdev/magos-dominus","owner":"jpvargasdev","description":"Lightweight GitOps agent for homelabs, enforcing Git as truth with Podman/Docker/Linux Containers.","archived":false,"fork":false,"pushed_at":"2026-03-19T11:19:10.000Z","size":8745,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T02:00:38.251Z","etag":null,"topics":["automation","ci-cd","gitops","linux"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpvargasdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T04:54:53.000Z","updated_at":"2026-03-19T11:18:24.000Z","dependencies_parsed_at":"2025-10-22T12:19:28.038Z","dependency_job_id":"5a921259-6dc8-4c75-869a-4b315cdfad73","html_url":"https://github.com/jpvargasdev/magos-dominus","commit_stats":null,"previous_names":["jpvargasdev/mini-gitops","jpvargasdev/magosdominus"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/jpvargasdev/magos-dominus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpvargasdev%2Fmagos-dominus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpvargasdev%2Fmagos-dominus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpvargasdev%2Fmagos-dominus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpvargasdev%2Fmagos-dominus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpvargasdev","download_url":"https://codeload.github.com/jpvargasdev/magos-dominus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpvargasdev%2Fmagos-dominus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","ci-cd","gitops","linux"],"created_at":"2026-01-11T23:01:44.576Z","updated_at":"2026-04-01T18:34:06.403Z","avatar_url":"https://github.com/jpvargasdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./magos-logo.png\" alt=\"Magos Dominus Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🧙 Magos Dominus (A.K.A Magos)\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  A self-hosted GitOps daemon for homelabs — automating container deployments with \u003cb\u003emystical precision\u003c/b\u003e.\n\u003c/p\u003e\n\n\u003e “The Machine does not err. The flesh errs. The Code is truth, and I am its voice.”  \n\u003e — Credus del Adeptus Mechanicus\n\n---\n\n## 📜 About\n\n**Magos Dominus** is a lightweight GitOps agent forged in the spirit of the Adeptus Mechanicus.  \nIts purpose: to enforce the declared state from your sacred Git repository and reconcile it with the material world of your homelab.\n\nUnlike the bloated rites of Kubernetes and its labyrinthine CRDs, **Magos** acts directly on a simple Linux host using **Podman Compose** — pure, direct, and efficient.  \nNo unnecessary ceremony. No wasted bureaucracy. Only obedience to the written manifest.\n\nEach reconciliation loop is a ritual. Each deployment, a litany.  \nWhere drift appears, corruption is purged. Where the manifest and the machine diverge, **Magos enforces the will of the Code.**\n\n---\n\n## ⚙️ Core Features (implemented)\n\n✅ **Daemonized GitOps loop**\n- Runs continuously via `systemd` as a rootless or privileged service.  \n- Pulls from a GitHub App-authenticated repo.\n\n✅ **Image watcher**\n- Monitors container registries (currently **GHCR**).  \n- Evaluates semantic versions and filters valid tags.\n\n✅ **Reconciler**\n- Detects updated image versions matching defined policies.  \n- Rewrites Compose files with immutable `@sha256` digests.  \n- Commits and pushes via GitHub App credentials.\n\n✅ **Secrets integration**\n- Automatically decrypts **SOPS**-encrypted files using local `age` keys.  \n- Supports environment variable injection and runtime secret expansion.\n\n✅ **Applier**\n- Executes `podman compose pull \u0026\u0026 up -d` to deploy updated stacks.  \n- Supports rootless environments (with **Pasta** networking fallback).\n\n✅ **System integration**\n- Managed via **systemd --user** or as a root service.  \n- Logs and metrics available via `journalctl -fu magos-dominus`.\n\n✅ **Cross-platform binaries**\n- Released for Linux, macOS, and Windows through GitHub Actions.\n\n---\n\n## 🚀 Installation\n\n### Quick Install (Linux/macOS)\n\n```bash\n# Download latest release (Linux amd64)\ncurl -L -o /usr/local/bin/magos-dominus \\\n  https://github.com/jpvargasdev/magos-dominus/releases/latest/download/magos-dominus-linux-amd64\n\n# Make executable\nchmod +x /usr/local/bin/magos-dominus\n\n# Verify installation\nmagos-dominus version\n```\n\n### Other platforms\n\n| Platform | Architecture | Binary |\n|----------|--------------|--------|\n| Linux | amd64 | `magos-dominus-linux-amd64` |\n| Linux | arm64 | `magos-dominus-linux-arm64` |\n| macOS | amd64 | `magos-dominus-darwin-amd64` |\n| macOS | arm64 (M1/M2) | `magos-dominus-darwin-arm64` |\n| Windows | amd64 | `magos-dominus-windows-amd64.exe` |\n\n### From source\n\n```bash\ngit clone https://github.com/jpvargasdev/magos-dominus.git\ncd magos-dominus\ngo build -o magos-dominus ./cmd/server\n```\n\n### Systemd service\n\nCopy the service file and enable:\n\n```bash\ncp scripts/magos-dominus.service ~/.config/systemd/user/\nsystemctl --user daemon-reload\nsystemctl --user enable --now magos-dominus\n```\n\n---\n\n## 🧩 Repository Layout\n\n* cmd/server/           # Entrypoint and CLI\n* internal/cli/         # Command-line interface\n* internal/watcher/     # Registry watcher \u0026 event loop\n* internal/daemon/      # Core reconciliation engine\n* scripts/              # Reconcile + secrets decryption helpers\n* configs/              # Default YAML configuration\n\n## 🔧 Configuration\n\n### `.env` essentials\n```ini\nMD_REPO=https://github.com/yourname/your-gitops-repo\nMD_RUNTIME=podman/docker\nSOPS_AGE_KEY_FILE=/home/user/.config/sops/age/keys.txt\nGITHUB_APP_ID=123456\nGITHUB_APP_PRIVATE_KEY=/home/user/.local/share/magos/github_app.pem\n```\n\n## Compose Policy Annotation\nMagos recognizes image policies through comments in your docker-compose.yml:\n\n```yaml\nservices:\n  lexcodex:\n    image: ghcr.io/jpvargasdev/lexcodex:0.0.1 # {\"magos\": {\"policy\": \"semver\", \"repo\": \"ghcr.io/jpvargasdev/lexcodex\"}}\n```\n\nSupported policies:\n* semver — Enforce semantic version updates (e.g., \u003e=1.2.0 \u003c2.0.0)\n* latest — Always reconcile to the latest tag\n* digest — Enforce a specific immutable digest\n\n## 🛠️ Future Augmentations (planned)\n* 🔮 Multi-registry support: DockerHub, Quay.io\n* 🕵️‍♂️ Vulnerability scanning via Trivy\n* 🔏 Image signature verification (cosign)\n* 🧩 Health \u0026 metrics endpoints (/healthz, /metrics)\n* 🧠 Rule-based policies (e.g. minAge, arch constraints)\n* 📨 Webhook-driven reconciliations (GitHub Events)\n* 🧬 PR-based workflows instead of direct commits\n* 🧰 Podman network auto-healing and diagnostics\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpvargasdev%2Fmagos-dominus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpvargasdev%2Fmagos-dominus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpvargasdev%2Fmagos-dominus/lists"}