localgenai/pyinfra/framework/README.md

# pyinfra: Strix Halo bring-up

Containerized setup for the Framework Desktop (Ryzen AI Max+ 395, Radeon
8060S, 128 GB). The host stays minimal — kernel + driver + Docker +
diagnostics. Inference engines (llama.cpp, vLLM, Ollama) run as docker
compose services, each shipping its own ROCm/Vulkan stack.

## Manual prerequisites

1. **Phase 0** — update Framework BIOS, set GPU UMA carve-out (96 GB).
2. **OS install** — Ubuntu Server 24.04 LTS. AMD ROCm only ships for
   jammy/noble; later Ubuntus install but break the host-side toolchain
   (libxml2 ABI). Enable SSH, import your laptop key, create user `noise`.
   Recommended partitioning: ≥300 GB on `/`, big disk mounted at `/models`,
   plain ext4 (skip LVM).
3. The host must be reachable at `10.0.0.237` over SSH (edit `inventory.py`
   if it moves).
4. **NOPASSWD sudo for `noise`** — pyinfra's fact layer doesn't reliably
   thread sudo passwords. One-time setup:
   ```sh
   ssh noise@10.0.0.237 'echo "noise ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/noise-nopasswd && sudo chmod 440 /etc/sudoers.d/noise-nopasswd'
   ```

## Run

```sh
uv tool install pyinfra
./run.sh           # equivalent to: pyinfra inventory.py deploy.py
./run.sh --dry     # any extra args are forwarded to pyinfra
```

Or run it ephemerally without installing: `uvx pyinfra inventory.py deploy.py`.

## What the deploy does

- Base CLI: tmux, vim, htop, btop, nvtop, amdgpu_top, uv, lazydocker, huggingface-cli
- Tailscale (run `sudo tailscale up` on the box once, interactively)
- Docker engine + compose plugin, user added to `docker` group
- ROCm host diagnostics only (`rocminfo`) — no full toolchain
- GRUB kernel params for Strix Halo perf: `amd_iommu=off`,
  `amdgpu.gttsize=117760` (per [Gygeek/Framework-strix-halo-llm-setup](https://github.com/Gygeek/Framework-strix-halo-llm-setup)).
  Requires a reboot to activate — pyinfra rewrites `/etc/default/grub`
  and runs `update-grub`, but won't reboot for you.
- `/models/<vendor>/` layout
- `/srv/docker/{llama,vllm,ollama,openwebui,beszel,openlit,phoenix,openhands,homepage,whisper,piper}/docker-compose.yml`
  dropped in, not auto-started — you edit the model path then
  `docker compose up -d`
  (OpenWebUI needs no edits — it's pre-configured to find Ollama at
  `host.docker.internal:11434` and uses `searxng.n0n.io` for web search)
  (Beszel hub at :8090, OpenLIT UI at :3001, Phoenix UI at :6006,
  OpenHands UI at :3030, Homepage at :7575, Whisper STT at :10300,
  Piper TTS at :10200 — see "Monitoring stack", "Agent harnesses",
  "Front door", and "Voice" below)

If a previous run installed the native llama.cpp build / full ROCm /
native Ollama, those are auto-cleaned the next time `./run.sh` runs.

## After the deploy: starting an inference service

```sh
ssh noise@10.0.0.237
sudo tailscale up                            # one-time, interactive

# Drop a GGUF somewhere under /models, then:
cd /srv/docker/llama
vim docker-compose.yml                       # edit the --model path
docker compose up -d
curl localhost:8080/v1/models                # smoke test
```

Same shape for `vllm` (port 8000) and `ollama` (port 11434, no model edit
needed — Ollama serves models on demand).

## Tunables

Top of `deploy.py`:
- `ROCM_VERSION` and `AMDGPU_INSTALL_DEB` — bump when AMD ships a newer
  release. The .deb filename has a build suffix that doesn't derive from
  the version; find it at https://repo.radeon.com/amdgpu-install/.
- `AMDGPU_TOP_VERSION` — bump when a newer release lands at
  https://github.com/Umio-Yasuno/amdgpu_top/releases.

Compose images in
`compose/{llama,vllm,ollama,openwebui,beszel,openlit,phoenix,openhands,homepage}.yml`
— pin tags here. Homepage's tile/layout config is in `compose/homepage/`
(`services.yaml`, `settings.yaml`, etc.); edit there, `./run.sh`, restart
the homepage container.

## Voice

Wyoming-protocol speech servers (Home Assistant's voice stack). No web
UI — these are TCP protocol servers consumable by HA Assist, Wyoming
satellites, or any Wyoming client.

- **Whisper** (`/srv/docker/whisper`, `tcp://framework:10300`) —
  speech-to-text. Default model is `tiny-int8` (~75 MB). Models
  download into `/srv/docker/whisper/data/` on first run.

- **Piper** (`/srv/docker/piper`, `tcp://framework:10200`) —
  text-to-speech. Default voice is `en_US-lessac-medium` (~63 MB).
  Browse alternatives at <https://github.com/rhasspy/piper/blob/master/VOICES.md>.

Bring-up:
```sh
cd /srv/docker/whisper && docker compose up -d
cd /srv/docker/piper && docker compose up -d
```

Both are conservative defaults sized for "small command-style usage";
on Strix Halo's hardware budget you can run substantially better
models. See [`localgenai/VoiceModels.md`](../../VoiceModels.md) for the
landscape and upgrade options.

## Front door

- **Homepage** (`/srv/docker/homepage`, http://framework:7575) — single
  page with one tile per service in this stack, with native widgets
  pulling live state (loaded models from Ollama, container status from
  the docker socket, etc.). Bookmarks for the reference docs across the
  bottom. Use as the default landing page on this network.

  Bring-up: `cd /srv/docker/homepage && docker compose up -d`. No
  first-run setup — it reads `/srv/docker/homepage/config/*.yaml` and
  renders.

  To customize: edit `pyinfra/framework/compose/homepage/*.yaml` in the
  repo, run `./run.sh`, then `docker compose restart homepage` on the
  box. Direct edits to `/srv/docker/homepage/config/*.yaml` will be
  overwritten on the next pyinfra deploy.

## Monitoring stack

Two compose stacks watch the inference services:

- **Beszel** (`/srv/docker/beszel`, http://framework:8090) — host + Docker
  container + AMD GPU dashboard. The agent's `amd_sysfs` collector reads
  `/sys/class/drm/cardN/device/` directly; this is the only path that
  reports real numbers on Strix Halo (gfx1151) — `amd-smi` returns N/A
  for util/power/temp on this APU.

  First-time bring-up:
  ```sh
  cd /srv/docker/beszel
  docker compose up -d beszel                                 # 1. hub
  # 2. open http://framework:8090 → create admin → "Add system"
  # 3. copy the TOKEN and the SSH KEY from the dialog into .env:
  sudo tee /srv/docker/beszel/.env >/dev/null <<EOF
  BESZEL_TOKEN=<token-from-dialog>
  BESZEL_KEY=ssh-ed25519 AAAA…
  EOF
  sudo chgrp docker /srv/docker/beszel/.env
  sudo chmod 640 /srv/docker/beszel/.env
  docker compose up -d --force-recreate beszel-agent          # 4. agent
  ```

- **OpenLIT** (`/srv/docker/openlit`, http://framework:3001) — fleet
  metrics for the LLM stack (cost, tokens, latency aggregated across
  sessions and models). Auto-instruments Ollama and vLLM via
  OpenTelemetry without app-code changes; for llama.cpp, the compose
  file already passes `--metrics` so OpenLIT can scrape `/metrics`.
  ClickHouse-backed. OTLP receivers exposed on the host at **:4327
  (gRPC) / :4328 (HTTP)** — Phoenix owns 4317/4318.

  Bring-up: `cd /srv/docker/openlit && docker compose up -d`. UI prompts
  to create an admin account on first load.

- **Phoenix** (`/srv/docker/phoenix`, http://framework:6006) — per-trace
  agent waterfall / flamegraph. Designed to answer "show me what one
  OpenCode turn actually did" — full call tree, nested LLM/tool calls,
  token counts inline. Single container, SQLite-backed. OTLP receivers
  on the host at **:4317 (gRPC)** and **:6006/v1/traces (HTTP)** —
  Phoenix 15.x serves HTTP OTLP on the UI port, not a separate 4318.

  Bring-up: `cd /srv/docker/phoenix && docker compose up -d`. UI
  immediately available; no auth in the self-hosted single-user path.

  See [`localgenai/opencode/README.md`](../../opencode/README.md) for
  how OpenCode is configured to ship traces here.

The official AMD Prometheus exporters (`amd-smi-exporter`,
`device-metrics-exporter`) are intentionally **not** deployed — they're
broken on gfx1151 (ROCm#6035). If you ever want full Prometheus +
Grafana, the migration path is to replace Beszel with `node_exporter` +
a textfile collector reading `/sys/class/drm/cardN/device/` and
`/sys/class/hwmon/`.

## Agent harnesses

Two agent UIs in front of the local model stack — pick one (or both)
based on how you like to drive the agent:

- **OpenWebUI** (`/srv/docker/openwebui`, http://framework:3000) —
  ChatGPT-style web UI. Pre-wired to Ollama + SearXNG web search.
  Best for casual chat and household-shared LLM access.

  Bring-up: `cd /srv/docker/openwebui && docker compose up -d`.

- **OpenHands** (`/srv/docker/openhands`, http://framework:3030) —
  autonomous agent in a Docker sandbox. Spawns a per-conversation
  `agent-server` container that can write code, run tests, browse the
  web. Pre-configured for Ollama at `openai/qwen3-coder:30b` over the
  OpenAI-compatible endpoint; ships traces to Phoenix.

  Bring-up: `cd /srv/docker/openhands && docker compose up -d`. First
  run pulls the agent-server image (~2 GB) lazily on first conversation,
  not at startup, so the orchestrator comes up fast but your first
  message takes 30–60 s. Pre-0.44 state path was `~/.openhands-state`;
  not relevant on a fresh install.

  > **Security note:** the orchestrator container has docker-socket
  > access and spawns code-running sandboxes. Fine to expose on a
  > Tailscale-only box; **change the compose port mapping back to
  > `127.0.0.1:3030:3000` and tunnel in** if this host ever sees LAN
  > or internet traffic.

  Tool-call quality with local models is much better when Ollama's
  context is bumped — the compose at `/srv/docker/ollama` already sets
  `OLLAMA_CONTEXT_LENGTH=65536`, which is plenty.

OpenCode (the terminal driver, configured in
[`localgenai/opencode/`](../../opencode/)) runs on the Mac and points
at the same Ollama endpoint, so all three harnesses share the same
model server.

The llama.cpp image is `kyuz0/amd-strix-halo-toolboxes:vulkan-radv`,
gfx1151-optimized with rocWMMA flash attention (the latter only kicks
in on the ROCm tags). Auto-rebuilt against llama.cpp master.