https://github.com/ggichuru/dgx-ops
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.
https://github.com/ggichuru/dgx-ops
agentic dgx-spark docker-compose gemma home-lab homepage llama-cpp llm mission-control ollama phoenix raspberry-pi self-hosted tailscale uptime-kuma vllm
Last synced: 1 day ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/ggichuru/dgx-ops
- Owner: ggichuru
- License: apache-2.0
- Created: 2026-05-08T16:12:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-19T10:58:31.000Z (17 days ago)
- Last Synced: 2026-06-19T12:28:45.958Z (17 days ago)
- 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
- Language: Python
- Homepage: https://github.com/ggichuru/dgx-ops/releases/tag/v0.1.0
- Size: 640 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Phoenix
[](LICENSE)
[](https://github.com/ggichuru/dgx-ops/releases)
[](phoenix/llm-models.yaml)
[](compose/phoenix-tiers/README.md)
[](docs/phoenix-architecture.md)
**A home-lab-in-a-box. Same UX on a Raspberry Pi 4 or an NVIDIA DGX Spark.**
> Phoenix turns any Linux device — Pi → mini-PC → workstation → DGX —
> into a self-hosted home lab. One command. Dashboard + monitoring
> are up in ~10 minutes on a fast link; LLM chat is additional (a
> model pull + init — longer on slow/metered links). Docker-based,
> auto-discovery for every container, an agent that picks the right
> LLM for your hardware, and optional Tailscale remote access. No
> cloud sign-up. No phone-home. Your data stays
> where you put it.
This repo started life as `dgx-ops`, a remote-ops scaffold for one
NVIDIA DGX Spark in Limuru, Kenya. The Spark stack still lives here
(everything outside `phoenix/` is unchanged and in production). The
Phoenix layer is the general-purpose transformation that lets the
same patterns run on whatever Linux box you already own.
Spark is the origin. Phoenix is what it became when it learned to fly.
## Quick install
```bash
# 1. Prerequisites (Ubuntu / Debian / Pi OS — adapt for your distro)
sudo apt-get install -y curl git jq python3 docker-compose-plugin
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER # then log out + back in
# 2. (Optional) Tailscale for remote access from anywhere
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --ssh
# Enable MagicDNS at https://login.tailscale.com/admin/dns
# 3. Clone + bootstrap
git clone https://github.com/ggichuru/dgx-ops.git ~/phoenix
cd ~/phoenix
bash phoenix/bootstrap.sh # dry-run: detects + prints plan
bash phoenix/bootstrap.sh --apply # brings up the stack
```
When `--apply` finishes you'll see the access URLs printed:
```text
┌──────────────────────────────────────────────────────────┐
│ Phoenix — access URLs │
├──────────────────────────────────────────────────────────┤
LAN : http://:8500/
Tailnet : http://..ts.net:8500/
Expose all : bash phoenix/exposed-services.sh.auto
└──────────────────────────────────────────────────────────┘
```
Open one of those in a browser. Done.
→ **Full walkthrough**: [`docs/phoenix-quickstart.md`](docs/phoenix-quickstart.md)
(every command, including Tailscale setup, verification, public
exposure via Funnel, and a cheat-sheet).
→ **Short reference**: [`INSTALL.md`](INSTALL.md).
→ **Architecture**: [`docs/phoenix-architecture.md`](docs/phoenix-architecture.md).
## What you get
A bespoke **adaptive dashboard** at `http://:8500/` —
"Apothecary": a calm sage + lavender botanical control surface with
dawn/dusk themes. It renders **entirely from discovered services**
(nothing hardcoded): every running container shows up in the right
bed — `roots` (databases), `instruments` (observability), `minds`
(LLM/agents), … — with the right icon and live status. Add a
container, the tile appears. Details:
[`docs/phoenix-dashboard.md`](docs/phoenix-dashboard.md). The generic
Homepage tile app is still available at `/homepage/`.
It also gives you:
- **Auto-discovered service classification** — the same engine feeds
the dashboard, Homepage tiles, the Caddy reverse-proxy, and the
Tailscale serve commands. Hand-curation optional, never required.
- **Uptime Kuma** — pings every service; pushes a notification on
failure.
- **ntfy** — phone push notifications from anywhere.
- **Open WebUI** (`small` tier and above) — chat interface pre-wired
to the LLM Phoenix picked for your hardware.
- **Beszel** (`mid` tier and above) — host metrics, agentless.
- **An agent** at `/v1/runtime` that knows what LLM you have and how
to reach it. Pure OpenAI-compatible API.
- **Mission Control** (DGX Spark tier) — bespoke single-pane-of-glass
ops dashboard.
…and Phoenix scales the stack down to what your hardware can run:
| Tier | Hardware | What runs |
|--------|--------------------------------|------------------------------------------------------------|
| nano | Pi Zero 2 / Pi 4 4 GB | caddy, homepage, kuma, ntfy, llama.cpp |
| small | Pi 5 8 GB / mini-PC no GPU | + ollama (CPU) + open-webui |
| mid | 16–32 GB, optional small GPU | + beszel + docs-hub |
| large | 32–64 GB or 8–24 GB GPU | + searxng + couchdb |
| xlarge | DGX Spark / ≥64 GB / ≥24 GB GPU | full stack + mission-control + optional vLLM |
The tier is a recommendation. Override in `.phoenix/profile.json`
if you know what you want.
## How it works
Phoenix is a small set of well-behaved tools:
```
phoenix/
├── detect.py probes the host → JSON
├── classify.py JSON in → tier + runtime + model
├── classifier-rules.yaml 55+ rules: image → role
├── discover.py scan docker, classify each container
├── render-homepage.py registry → homepage tiles
├── render-caddy.py registry → reverse-proxy snippets
├── render-tailscale.sh registry → tailscale serve commands
├── llm-picker.py standalone runtime+model picker
├── install-llm.sh idempotent installer
└── bootstrap.sh one-command entrypoint
```
The contract between tools is **JSON files**. Read them. Edit them
if Phoenix guessed wrong. Re-run. No magic.
Architecture diagram and design notes:
[`docs/phoenix-architecture.md`](docs/phoenix-architecture.md).
## Optional: remote access from anywhere
Phoenix is tailnet-first. With [Tailscale](https://tailscale.com) up,
every service Phoenix discovers gets a runnable command:
```bash
bash phoenix/exposed-services.sh.auto
```
Each service then has its own `https://...ts.net`
URL. Works through CGNAT, hotel WiFi, mobile networks. Free for
personal use. No port forwarding on your router.
## What's honest about v0.1
- Tested on the DGX Spark (`xlarge`), Pi 5 (`small`), and one x86
workstation (`mid`). Other configurations should work by extension
— if they don't, [file an issue](CONTRIBUTING.md).
- vLLM on aarch64 is included but performance hasn't been tuned. The
default for high-end aarch64 is Ollama with Gemma 3 12B.
- AMD GPU detection works; AMD inference doesn't yet (no ROCm path).
- The auto-rendered Caddyfile is a *snippet* — operators still
`import` it into the main Caddyfile. v0.2 plumbs this end-to-end.
- Air-gapped install isn't supported yet.
- Multi-host orchestration isn't supported yet.
We mark beta what's beta and stable what's stable.
[`docs/phoenix-architecture.md`](docs/phoenix-architecture.md) has the
full honest scope.
## Production-ready means honest
Phoenix is open-source and ready to be criticized. The conviction:
running your own compute at home — and having it work from anywhere —
should not require a cloud account or a six-figure rack.
If you read the code and see how to make that more true,
[send a change](CONTRIBUTING.md).
## License
[Apache 2.0](LICENSE).
## Origin: the DGX Spark stack
The original `dgx-ops` content — the systemd units, the curated
compose stack, the Mission Control dashboard, the agent-service with
its 8 personas, the Tailscale ACLs, the Kenya-realities runbook —
all still lives in this repo, unchanged. Phoenix is layered on top;
the Spark stack remains the production deployment at the Limuru site.
If you want the Spark-specific content:
- [`docs/agent-architecture.md`](docs/agent-architecture.md) — three
layers (deterministic / bash / FastAPI).
- [`docs/sovereignty.md`](docs/sovereignty.md) — running with zero
cloud dependency.
- [`docs/agent-security.md`](docs/agent-security.md) — threat model
and audit findings.
- [`docs/learning-loop.md`](docs/learning-loop.md) — bandit-style
continual learning.
- [`docs/mission-control.md`](docs/mission-control.md) — Coolify
install + integration.
- The skill at `~/.claude/skills/dgx-spark-remote-ops/SKILL.md`.
The Spark stack uses ports 8190 / 8443–8470 and is hostname-locked
to `spark-5804`. Phoenix uses port 8500 as its single ingress and
works on any hostname. They coexist cleanly on the same box.
## See also
- [`INSTALL.md`](INSTALL.md) — install instructions, troubleshooting,
exposing services.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to propose a change,
what we want, what we don't.
- [`docs/phoenix-architecture.md`](docs/phoenix-architecture.md) —
the design notes.
- [`compose/phoenix-tiers/README.md`](compose/phoenix-tiers/README.md)
— per-tier compose specifics.
- [`phoenix/README.md`](phoenix/README.md) — module-level overview.
— maintained with love. built on a Spark. it is a phoenix.