{"id":51431751,"url":"https://github.com/ggichuru/dgx-ops","last_synced_at":"2026-07-05T04:30:46.046Z","repository":{"id":365902806,"uuid":"1233128277","full_name":"ggichuru/dgx-ops","owner":"ggichuru","description":"Phoenix — universal home-lab-in-a-box. Same UX on a Raspberry Pi or an NVIDIA DGX Spark. One command, Docker-based, agent picks the right LLM, auto-discovers services, Tailscale-ready. Apache 2.0.","archived":false,"fork":false,"pushed_at":"2026-06-19T10:58:31.000Z","size":655,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T12:28:45.958Z","etag":null,"topics":["agentic","dgx-spark","docker-compose","gemma","home-lab","homepage","llama-cpp","llm","mission-control","ollama","phoenix","raspberry-pi","self-hosted","tailscale","uptime-kuma","vllm"],"latest_commit_sha":null,"homepage":"https://github.com/ggichuru/dgx-ops/releases/tag/v0.1.0","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ggichuru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2026-05-08T16:12:02.000Z","updated_at":"2026-05-27T05:54:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ggichuru/dgx-ops","commit_stats":null,"previous_names":["ggichuru/dgx-ops"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/ggichuru/dgx-ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggichuru%2Fdgx-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggichuru%2Fdgx-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggichuru%2Fdgx-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggichuru%2Fdgx-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ggichuru","download_url":"https://codeload.github.com/ggichuru/dgx-ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ggichuru%2Fdgx-ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35143802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic","dgx-spark","docker-compose","gemma","home-lab","homepage","llama-cpp","llm","mission-control","ollama","phoenix","raspberry-pi","self-hosted","tailscale","uptime-kuma","vllm"],"created_at":"2026-07-05T04:30:45.379Z","updated_at":"2026-07-05T04:30:46.032Z","avatar_url":"https://github.com/ggichuru.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phoenix\n\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/ggichuru/dgx-ops?include_prereleases\u0026sort=semver)](https://github.com/ggichuru/dgx-ops/releases)\n[![Models](https://img.shields.io/badge/models-7_families%20%C3%97_3%2B_variants-orange)](phoenix/llm-models.yaml)\n[![Tiers](https://img.shields.io/badge/tiers-nano_%E2%86%92_xlarge-purple)](compose/phoenix-tiers/README.md)\n[![Platform](https://img.shields.io/badge/platform-Pi_%E2%86%92_DGX_Spark-success)](docs/phoenix-architecture.md)\n\n**A home-lab-in-a-box. Same UX on a Raspberry Pi 4 or an NVIDIA DGX Spark.**\n\n\u003e Phoenix turns any Linux device — Pi → mini-PC → workstation → DGX —\n\u003e into a self-hosted home lab. One command. Dashboard + monitoring\n\u003e are up in ~10 minutes on a fast link; LLM chat is additional (a\n\u003e model pull + init — longer on slow/metered links). Docker-based,\n\u003e auto-discovery for every container, an agent that picks the right\n\u003e LLM for your hardware, and optional Tailscale remote access. No\n\u003e cloud sign-up. No phone-home. Your data stays\n\u003e where you put it.\n\nThis repo started life as `dgx-ops`, a remote-ops scaffold for one\nNVIDIA DGX Spark in Limuru, Kenya. The Spark stack still lives here\n(everything outside `phoenix/` is unchanged and in production). The\nPhoenix layer is the general-purpose transformation that lets the\nsame patterns run on whatever Linux box you already own.\n\nSpark is the origin. Phoenix is what it became when it learned to fly.\n\n## Quick install\n\n```bash\n# 1. Prerequisites (Ubuntu / Debian / Pi OS — adapt for your distro)\nsudo apt-get install -y curl git jq python3 docker-compose-plugin\ncurl -fsSL https://get.docker.com | sh\nsudo usermod -aG docker $USER                # then log out + back in\n\n# 2. (Optional) Tailscale for remote access from anywhere\ncurl -fsSL https://tailscale.com/install.sh | sh\nsudo tailscale up --ssh\n# Enable MagicDNS at https://login.tailscale.com/admin/dns\n\n# 3. Clone + bootstrap\ngit clone https://github.com/ggichuru/dgx-ops.git ~/phoenix\ncd ~/phoenix\nbash phoenix/bootstrap.sh                    # dry-run: detects + prints plan\nbash phoenix/bootstrap.sh --apply            # brings up the stack\n```\n\nWhen `--apply` finishes you'll see the access URLs printed:\n\n```text\n┌──────────────────────────────────────────────────────────┐\n│  Phoenix — access URLs                                   │\n├──────────────────────────────────────────────────────────┤\n  LAN          : http://\u003cyour-box-ip\u003e:8500/\n  Tailnet      : http://\u003chost\u003e.\u003ctailnet\u003e.ts.net:8500/\n  Expose all   : bash phoenix/exposed-services.sh.auto\n└──────────────────────────────────────────────────────────┘\n```\n\nOpen one of those in a browser. Done.\n\n→ **Full walkthrough**: [`docs/phoenix-quickstart.md`](docs/phoenix-quickstart.md)\n  (every command, including Tailscale setup, verification, public\n  exposure via Funnel, and a cheat-sheet).\n\n→ **Short reference**: [`INSTALL.md`](INSTALL.md).\n\n→ **Architecture**: [`docs/phoenix-architecture.md`](docs/phoenix-architecture.md).\n\n## What you get\n\nA bespoke **adaptive dashboard** at `http://\u003cyour-box\u003e:8500/` —\n\"Apothecary\": a calm sage + lavender botanical control surface with\ndawn/dusk themes. It renders **entirely from discovered services**\n(nothing hardcoded): every running container shows up in the right\nbed — `roots` (databases), `instruments` (observability), `minds`\n(LLM/agents), … — with the right icon and live status. Add a\ncontainer, the tile appears. Details:\n[`docs/phoenix-dashboard.md`](docs/phoenix-dashboard.md). The generic\nHomepage tile app is still available at `/homepage/`.\n\nIt also gives you:\n\n- **Auto-discovered service classification** — the same engine feeds\n  the dashboard, Homepage tiles, the Caddy reverse-proxy, and the\n  Tailscale serve commands. Hand-curation optional, never required.\n- **Uptime Kuma** — pings every service; pushes a notification on\n  failure.\n- **ntfy** — phone push notifications from anywhere.\n- **Open WebUI** (`small` tier and above) — chat interface pre-wired\n  to the LLM Phoenix picked for your hardware.\n- **Beszel** (`mid` tier and above) — host metrics, agentless.\n- **An agent** at `/v1/runtime` that knows what LLM you have and how\n  to reach it. Pure OpenAI-compatible API.\n- **Mission Control** (DGX Spark tier) — bespoke single-pane-of-glass\n  ops dashboard.\n\n…and Phoenix scales the stack down to what your hardware can run:\n\n| Tier   | Hardware                       | What runs                                                  |\n|--------|--------------------------------|------------------------------------------------------------|\n| nano   | Pi Zero 2 / Pi 4 4 GB          | caddy, homepage, kuma, ntfy, llama.cpp                     |\n| small  | Pi 5 8 GB / mini-PC no GPU     | + ollama (CPU) + open-webui                                |\n| mid    | 16–32 GB, optional small GPU   | + beszel + docs-hub                                        |\n| large  | 32–64 GB or 8–24 GB GPU        | + searxng + couchdb                                        |\n| xlarge | DGX Spark / ≥64 GB / ≥24 GB GPU | full stack + mission-control + optional vLLM               |\n\nThe tier is a recommendation. Override in `.phoenix/profile.json`\nif you know what you want.\n\n## How it works\n\nPhoenix is a small set of well-behaved tools:\n\n```\nphoenix/\n├── detect.py              probes the host → JSON\n├── classify.py            JSON in → tier + runtime + model\n├── classifier-rules.yaml  55+ rules: image → role\n├── discover.py            scan docker, classify each container\n├── render-homepage.py     registry → homepage tiles\n├── render-caddy.py        registry → reverse-proxy snippets\n├── render-tailscale.sh    registry → tailscale serve commands\n├── llm-picker.py          standalone runtime+model picker\n├── install-llm.sh         idempotent installer\n└── bootstrap.sh           one-command entrypoint\n```\n\nThe contract between tools is **JSON files**. Read them. Edit them\nif Phoenix guessed wrong. Re-run. No magic.\n\nArchitecture diagram and design notes:\n[`docs/phoenix-architecture.md`](docs/phoenix-architecture.md).\n\n## Optional: remote access from anywhere\n\nPhoenix is tailnet-first. With [Tailscale](https://tailscale.com) up,\nevery service Phoenix discovers gets a runnable command:\n\n```bash\nbash phoenix/exposed-services.sh.auto\n```\n\nEach service then has its own `https://\u003csvc\u003e.\u003chost\u003e.\u003ctailnet\u003e.ts.net`\nURL. Works through CGNAT, hotel WiFi, mobile networks. Free for\npersonal use. No port forwarding on your router.\n\n## What's honest about v0.1\n\n- Tested on the DGX Spark (`xlarge`), Pi 5 (`small`), and one x86\n  workstation (`mid`). Other configurations should work by extension\n  — if they don't, [file an issue](CONTRIBUTING.md).\n- vLLM on aarch64 is included but performance hasn't been tuned. The\n  default for high-end aarch64 is Ollama with Gemma 3 12B.\n- AMD GPU detection works; AMD inference doesn't yet (no ROCm path).\n- The auto-rendered Caddyfile is a *snippet* — operators still\n  `import` it into the main Caddyfile. v0.2 plumbs this end-to-end.\n- Air-gapped install isn't supported yet.\n- Multi-host orchestration isn't supported yet.\n\nWe mark beta what's beta and stable what's stable.\n[`docs/phoenix-architecture.md`](docs/phoenix-architecture.md) has the\nfull honest scope.\n\n## Production-ready means honest\n\nPhoenix is open-source and ready to be criticized. The conviction:\nrunning your own compute at home — and having it work from anywhere —\nshould not require a cloud account or a six-figure rack.\n\nIf you read the code and see how to make that more true,\n[send a change](CONTRIBUTING.md).\n\n## License\n\n[Apache 2.0](LICENSE).\n\n## Origin: the DGX Spark stack\n\nThe original `dgx-ops` content — the systemd units, the curated\ncompose stack, the Mission Control dashboard, the agent-service with\nits 8 personas, the Tailscale ACLs, the Kenya-realities runbook —\nall still lives in this repo, unchanged. Phoenix is layered on top;\nthe Spark stack remains the production deployment at the Limuru site.\n\nIf you want the Spark-specific content:\n\n- [`docs/agent-architecture.md`](docs/agent-architecture.md) — three\n  layers (deterministic / bash / FastAPI).\n- [`docs/sovereignty.md`](docs/sovereignty.md) — running with zero\n  cloud dependency.\n- [`docs/agent-security.md`](docs/agent-security.md) — threat model\n  and audit findings.\n- [`docs/learning-loop.md`](docs/learning-loop.md) — bandit-style\n  continual learning.\n- [`docs/mission-control.md`](docs/mission-control.md) — Coolify\n  install + integration.\n- The skill at `~/.claude/skills/dgx-spark-remote-ops/SKILL.md`.\n\nThe Spark stack uses ports 8190 / 8443–8470 and is hostname-locked\nto `spark-5804`. Phoenix uses port 8500 as its single ingress and\nworks on any hostname. They coexist cleanly on the same box.\n\n## See also\n\n- [`INSTALL.md`](INSTALL.md) — install instructions, troubleshooting,\n  exposing services.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to propose a change,\n  what we want, what we don't.\n- [`docs/phoenix-architecture.md`](docs/phoenix-architecture.md) —\n  the design notes.\n- [`compose/phoenix-tiers/README.md`](compose/phoenix-tiers/README.md)\n  — per-tier compose specifics.\n- [`phoenix/README.md`](phoenix/README.md) — module-level overview.\n\n— maintained with love. built on a Spark. it is a phoenix.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggichuru%2Fdgx-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fggichuru%2Fdgx-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fggichuru%2Fdgx-ops/lists"}