🌍 Terrella — Personal AI Stack

A terrella ("little Earth") is the small magnetized model of Earth that early scientists ran lab experiments on. This one is a homelab-scale AI stack — born on a desktop PC named earth (ADR-0008 has the naming story).

A reproducible setup for a personal AI workstation — Fedora Linux (primary) or WSL2/Ubuntu (supported) with an NVIDIA RTX 5080 — running local LLMs (via ollama) for everyday coding, with paid cloud APIs (Anthropic / Gemini / OpenAI) reserved for hard problems. Every API call is logged to Postgres and visualized in Grafana, so total spend across local + paid services is always one chart away.

🧭 Direction & roadmap

This project is evolving from a workstation blueprint into an installable open-source tool — a terrella CLI that provisions and manages a personal AI stack on any Linux box, running on Podman + Quadlets, with a multi-node homelab as the end state. The plan lives in ROADMAP.md (phases M0–M7), architectural decisions in docs/adr/, and work tracking in docs/project-management.md.

Transition note: earth (the reference machine) now runs Fedora 44; the docs below still describe the WSL-era setup and are being migrated as part of M0. The stack/ and provision/ trees remain the working reference until the CLI reproduces them (see the transition policy in ROADMAP.md).

Open WebUI (chat for humans)  ──┐
                                ├──►  ollama  ──►  RTX 5080
LiteLLM (proxy for programs)  ──┘     :11434
       │
       ├─►  Anthropic / Gemini / OpenAI  (per-call cost logged)
       └─►  Postgres → Grafana          (one dashboard, all spend)

📚 Full documentation: docs/

The whole guide lives under docs/ and is structured for someone building this from scratch.

Repo contents

Quickstart for a fresh install

1. On Windows: install the NVIDIA driver, wsl --install -d Ubuntu-24.04, create %UserProfile%\.wslconfig (template in docs/setup/01-windows-host.md), then wsl --shutdown.
2. In WSL: clone this repo and run the provisioner:

   cd ~/src/jomkz/terrella
   bash provision/provision.sh
   

   Details: docs/setup/README.md.
3. Bring up the full stack:

   cd stack
   ./scripts/generate-env.sh   # first time only — writes .env with random secrets
   docker compose up -d
   ./scripts/init-billing-table.sh   # first time only — creates monthly_costs table
   ./scripts/init-benchmark-table.sh # first time only — creates benchmark_results table
   

   → Open WebUI http://127.0.0.1:8080 · LiteLLM http://127.0.0.1:4000 · Grafana http://127.0.0.1:3000.

Already set up — common tasks