145 lines
6.2 KiB
Markdown
145 lines
6.2 KiB
Markdown
# Tools Software WebUI
|
||
|
||
**One interface layer for the AI tool system: a multi-machine agent console (Pi Dashboard), LLM
|
||
routing (OmniRoute), automation (n8n · Prefect · LangChain), and a per-folder pi-agent model — all
|
||
self-hosted on a home network.**
|
||
|
||
> Developed by Sam · [tools-software-webui](https://gitea.lab.audasmedia.com.au/sam/tools-software-webui "Gitea") ·
|
||
> interactive map at [maps.lab.audasmedia.com.au](https://maps.lab.audasmedia.com.au)
|
||
|
||
---
|
||
|
||
## What it is
|
||
|
||
A coherent tool ecosystem for driving **pi** (the AI coding agent) from anywhere: watch what every
|
||
agent is doing on every machine, route its LLM traffic through one resilient proxy, automate around
|
||
it, and keep each project's context lean with a strict per-folder model.
|
||
|
||
Built on four layers that compose cleanly:
|
||
|
||
| Layer | Tool | Role |
|
||
|---|---|---|
|
||
| Console | **Pi Dashboard** (Go TUI + Python portal) | Live view of every pi session on every machine — what's running, where, status |
|
||
| LLM routing | **OmniRoute** | One proxy, prioritized "combo" fallback chains (OpenCode-Go → OpenRouter → DeepSeek → Gemini) |
|
||
| Automation | **n8n · Prefect 3 · LangChain** | Visual workflows, code pipelines, Python glue |
|
||
| AI toolkit | **pi + extensions + MCP** | Sub-agent orchestration, tasks, memory, LSP, dashboards |
|
||
|
||
## Architecture
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph CLIENTS["Clients"]
|
||
D27[".27 main dev<br/>NixOS"]
|
||
D51[".51 laptop<br/>NixOS"]
|
||
M["Mobile<br/>Termux / Tailscale / KDE Connect"]
|
||
end
|
||
subgraph LAB["Home lab (.lab.audasmedia.com.au)"]
|
||
C["Caddy reverse proxy<br/>.35"]
|
||
G["Gitea<br/>.35 :3001/:2222"]
|
||
P["Pi-hole DNS<br/>.35"]
|
||
end
|
||
subgraph S13["Web-facing + Docker host (.13)"]
|
||
N["n8n :5678"]
|
||
PR["Prefect 3 :4200"]
|
||
OR["OmniRoute :20129"]
|
||
OW["Open WebUI :3000"]
|
||
POR["Console portal :8500"]
|
||
DSH["dsh chat :3081-84"]
|
||
JK["Jervis voice :8501"]
|
||
EN["engram .13:7437"]
|
||
HH["headroom :8787"]
|
||
end
|
||
subgraph AGENTS["pi agents (per machine)"]
|
||
EXT["dashboard.ts ext"]
|
||
SUB["pi-subagents 18 types"]
|
||
TS["pi-tasks"]
|
||
MCP["MCP servers"]
|
||
end
|
||
D27 -->|"pi sessions"| AGENTS
|
||
D51 -->|"pi sessions"| AGENTS
|
||
M -->|"Tailscale / SSH"| D27
|
||
M -->|"NTFY alerts"| AGENTS
|
||
AGENTS -->|"state JSON"| EXT
|
||
EXT -->|"~/.pi/agent/dashboard"| POR
|
||
EXT -->|"notify"| M
|
||
AGENTS -->|"LLM (omni provider)"| OR
|
||
OR -->|"Caddy"| C
|
||
C -->|"gitea.lab"| G
|
||
C -->|"n8n/console.lab"| S13
|
||
N -.->|"webhooks / triggers"| AGENTS
|
||
PR -.->|"pipelines"| AGENTS
|
||
AGENTS -->|"compress"| HH
|
||
AGENTS -->|"memory"| EN
|
||
```
|
||
|
||
## How it works
|
||
|
||
1. **Every pi session reports.** A `dashboard.ts` extension writes heartbeat state to
|
||
`~/.pi/agent/dashboard/<session>.json` (cwd/folder, agent status, model, attach target).
|
||
2. **State is collected on the server.** The Go TUI (`pi-dashboard`) polls local + remote state over
|
||
SSH; the Python console portal renders it in a browser.
|
||
3. **Act from one table.** Attach to any session, review its changes with Hunk, open its task board
|
||
(Tuxedo) — notifications via NTFY/Apprise.
|
||
4. **LLM traffic is proxied.** pi talks to the `omni` provider; OmniRoute applies priority fallback
|
||
combos so work continues if one provider fails.
|
||
5. **Automation wraps it.** n8n webhooks and Prefect pipelines trigger around the agents.
|
||
|
||
## Directory map
|
||
|
||
```
|
||
tools-software-webui/
|
||
├── README.md ← this file
|
||
└── docs/
|
||
├── system.mmd ← Mermaid source (single source of truth)
|
||
├── system-map.html ← interactive Archify architecture map
|
||
└── diagrams/
|
||
├── system.png ← rendered diagram (PNG, 2×)
|
||
└── system.svg ← rendered diagram (vector)
|
||
```
|
||
|
||
## Access
|
||
|
||
| Target | Route |
|
||
|---|---|
|
||
| Console (agent table) | Go TUI on `.27`/`.13` · web: Admin → Pi Dashboard (portal :8500 via Caddy) |
|
||
| n8n | `n8n.home.lab` (LAN + auth) or Tailscale direct |
|
||
| Prefect | CLI/API from dev machines → `http://<server-13>:4200` |
|
||
| OmniRoute (OpenAI-compatible) | `http://192.168.20.13:20129/v1` · `https://omniroute.lab.audasmedia.com.au/v1` |
|
||
| Open WebUI | `http://192.168.20.13:3000` |
|
||
| Gitea | `gitea.lab.audasmedia.com.au` (:3001 web / :2222 ssh) |
|
||
| Mobile | Tailscale app · Termux (SSH) · KDE Connect · NTFY alerts |
|
||
|
||
## Technology stack
|
||
|
||
- **pi** — Nix-managed coding agent (uniform v0.82.1 on `.27/.13/.51`); global packages:
|
||
`pi-memctx`, `pi-mcp-adapter`, `@tintinweb/pi-subagents` (18 agents), `@tintinweb/pi-tasks`,
|
||
`omniroute-pi-ext-integration`; MCP servers (`codebase-memory`, `code-review-graph`).
|
||
- **Pi Dashboard** — Go + Bubble Tea TUI, `dashboard.ts` extension, Tuxedo (todo.txt), Hunk (diff),
|
||
NTFY/Apprise notifications.
|
||
- **OmniRoute** — Docker LLM proxy on `.13` with combo routing (484 models).
|
||
- **Automation** — n8n (visual), Prefect 3 (code pipelines), LangChain (Python library).
|
||
- **Services** — Outline (docs), Vikunja (tasks), Gitea (git + asset source `pi-config`),
|
||
Caddy (reverse proxy), Pi-hole (DNS), Tailscale (mesh VPN).
|
||
- **Infra** — NixOS `.27/.13/.51`, Ubuntu Docker host `.35`, Proxmox `.28`.
|
||
|
||
## Why it matters
|
||
|
||
- **One console, every machine.** Attach to, review, and task-track any pi agent from any device —
|
||
no separate dashboards per host.
|
||
- **Resilient LLM access.** Combo routing means provider outages degrade gracefully, not stop work.
|
||
- **Lean by design.** Per-folder `.pi/settings.json` (arrays replace, not merge) keeps each
|
||
project's agent context minimal; Nix manages the pi binary uniformly.
|
||
- **Agent coordination built in.** 18 sub-agent types, worktrees, scheduling, dependency-tracked
|
||
tasks — a base that scales to multi-agent project work.
|
||
|
||
## Related projects
|
||
|
||
- [pi-dashboard](https://gitea.lab.audasmedia.com.au/sam/pi-dashboard) — the Go console viewer
|
||
- [family_home_lab](https://gitea.lab.audasmedia.com.au/sam/family_home_lab) — the family console
|
||
the portal is part of
|
||
- Docs: Obsidian `200 projects/Tools Software WebUI/` · Outline project `Tools Software WebUI` ·
|
||
Vikunja project `Tools Software WebUI`
|
||
|
||
---
|
||
|
||
*Documentation-only project — no proprietary code included. Secrets never appear in this repo.* |