🌍 Terrella — Personal AI Stack

License: Apache-2.0 OpenSSF Scorecard

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.

Section What's inside
docs/01-overview.md Architecture, glossary, and what's in the repo. Start here.
docs/setup/ Six-phase installation guide (Windows host → WSL → ollama → Open WebUI → Aider → observability stack).
docs/reference/ Look-up docs: machines, installed models, subscriptions, per-tool inventory, and the model-routing decision table.
docs/operations/ Day-2: cross-machine (Tailscale) access, backups, gaming toggle, model benchmarking, monthly billing entry, troubleshooting.

Repo contents

Path Purpose
docs/ All documentation.
provision/ Machine provisioner (provision.sh), model manager (sync-models.sh), and the model catalog (models.list). Run them independently.
stack/ docker-compose project: all runtime services — Open WebUI + LiteLLM + Postgres + Prometheus + Grafana. Config files mounted into containers live under stack/observability/.

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

Task Doc
Pick a model for the task at hand docs/reference/routing.md
Use the workstation from jupiter / Mac mini docs/operations/cross-machine-access.md
Measure how fast local models run (tok/s, TTFT, VRAM) docs/operations/benchmarking.md
Stop everything before launching a game docs/operations/maintenance.md#gaming-toggle
Back up Open WebUI chats docs/operations/maintenance.md#backup--restore-open-webui
Log this month's Copilot / Claude bill deploy/earth/manual-billing.md
Something broke docs/operations/troubleshooting.md

Project links

Data verified by PyPI on Jul 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jomkz from gravatar.com jomkz

Credits

Author: John McKenzie

GitHub Statistics

Data verified by PyPI on Jul 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.12

Tags

ai homelab litellm llm ollama podman quadlets

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

terrella-0.0.1.tar.gz (107.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

terrella-0.0.1-py3-none-any.whl (7.9 kB view details)

Uploaded Python 3

File details

Details for the file terrella-0.0.1.tar.gz.

File metadata

  • Download URL: terrella-0.0.1.tar.gz
  • Upload date:
  • Size: 107.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for terrella-0.0.1.tar.gz
Algorithm Hash digest
SHA256 45680f496ba551c61d2211739ae0273545b5a2f8441e15441f0ee3d69722fb38
MD5 0f6807b5c2cf062d63b24b38c0b40832
BLAKE2b-256 a040452ad4209a3d5652b8ca96b55b0b99c9cd6b8fcbd1a1e6961867a0cd24c4

See more details on using hashes here.

Provenance

The following attestation bundles were made for terrella-0.0.1.tar.gz:

Publisher: release.yml on terrella-project/terrella

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file terrella-0.0.1-py3-none-any.whl.

File metadata

  • Download URL: terrella-0.0.1-py3-none-any.whl
  • Upload date:
  • Size: 7.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for terrella-0.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 81c123c0b6a77e15a268e7e87e20c020ad24bdcf8c535ea8af457145559e31f0
MD5 56c4567326dd70a4880fc56b58d1e54a
BLAKE2b-256 5bbf1661e1afc7ffd9abdc2db5c14ff7ab5a6f94c2148da05b42e10b227b5e02

See more details on using hashes here.

Provenance

The following attestation bundles were made for terrella-0.0.1-py3-none-any.whl:

Publisher: release.yml on terrella-project/terrella

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page