# LLMHosts.com -- Detailed Roadmap

## META
- layer: 2 of 3 (Detailed)
- synced_with: executive.md, full-pm.md
- last_updated: 2026-02-22
- version: 4.0 (STATUS SYNC)

## PHASE 1: CLI + LOCAL INTELLIGENCE (Weeks 1-6) — COMPLETE

### Week 1-2: Core Proxy + Router + Discovery
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Python package skeleton (tiered: `llmhosts`, `[smart]`, `[full]`) | Onboarding | None | `pip install llmhosts` works |
| OpenAI + Anthropic compatible proxy (FastAPI, /v1/chat/completions + /v1/messages, streaming) | Conductor | Package | Proxy accepts both dialects |
| Ollama auto-discovery (detect running Ollama, list models, VRAM usage) | Compute Fabric | Proxy | Models discovered |
| Hardware discovery (GPU type/VRAM, CPU, RAM, installed tunnel tools) | Compute Fabric | None | Hardware inventory |
| BYOK cloud fallback (LiteLLM config for OpenAI/Anthropic keys) | Compute Fabric | Proxy | Cloud routing works |
| Rule-based router v1 (Tier 0: model matching, cost heuristic, availability) | Conductor | Proxy + discovery | Deterministic routing |
| `llmhosts serve` command (proxy + discovery + dashboard + tier detection) | Onboarding | All above | Single command entry |
| Docker alternative (`docker run llmhost/llmhost` with [full] tier) | Onboarding | Package | Docker path works |
| Dockerfile + docker-compose for dev stack | DevOps | None | Dev environment |

### Week 3-4: Cache + Router Intelligence + Cost Tracking
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Exact hash cache Tier 0 (SHA-256 normalized prompt) | Caching | Proxy | Exact matches cached |
| Entity-aware namespace filter Tier 1 (lightweight NER) | Caching | Hash cache | Cross-domain isolation |
| vCache verified semantic cache Tier 2 (per-prompt adaptive thresholds, ONNX) | Caching | Namespace filter | <1% false positive cache |
| Cost tracking with honest baselines (onboarding baseline capture) | Conductor | Proxy + routing | Real savings data |
| Embedding pipeline (all-MiniLM-L6-v2 via ONNX Runtime, 5% exploration) | Conductor | None | Embeddings + training data |
| kNN router prototype Tier 1 (FAISS, confidence threshold 0.85) | Conductor | Embeddings | kNN routing available |
| ModernBERT classifier prototype Tier 2 (6-signal analysis) | Conductor | Embeddings + data | Intelligent classification |
| `llmhosts keys add/remove/list` (BYOK management) | Onboarding | LiteLLM | Key management CLI |
| Request logging (SQLite: routing decisions, tier used, costs) | Observability | Proxy | Audit trail |

### Week 5-6: Dashboard + Polish + Release
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| TUI dashboard (textual/rich: savings ticker, request log with routing decisions, cache per tier) | Frontend | Cost tracking | TUI dashboard |
| Localhost web dashboard (React, WebSocket: real-time savings with honest baseline) | Frontend | Cost tracking | Web dashboard |
| Routing decision transparency (per-request: tier, model, reason, confidence) | Frontend | Dashboard + routing | Trust built |
| Onboarding baseline capture ("How much do you spend on AI?") | Frontend | Dashboard | Real comparison baseline |
| `llmhosts doctor` (verify Ollama, keys, proxy, cache, tier capabilities) | Onboarding | All above | Post-install verification |
| Cloud cost intelligence dashboard (freemium SaaS, $19/mo Pro) | Frontend | Cost tracking | FIRST REVENUE |
| README, docs, quickstart for all 3 install tiers | Docs | All above | Documentation |
| GitHub Actions CI (lint, test, build, publish all tiers to PyPI + Docker Hub) | DevOps | Package | CI/CD pipeline |
| Open source release (MIT license, GitHub repo) | Launch | All above | Public release |

### Critical Path: Package skeleton -> Proxy (both dialects) -> Discovery -> Router -> vCache -> Dashboard -> Cloud SaaS -> Release
### Revenue: Cloud cost intelligence dashboard ($19/mo Pro) launches with open source release
### Resource Needs: 1 developer (full-stack), $0 infrastructure (all local)

---

## PHASE 2: YOUR GPU FROM ANYWHERE (Weeks 7-14) — COMPLETE

### Week 7-8: Tunnel + Multi-Device + Web Dashboard
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| `llmhosts tunnel` command (auto-detect Tailscale/Cloudflare, guide install) | Compute Fabric | Phase 1 proxy | Remote GPU access |
| `llmhosts tunnel --public` (shareable URL, rate limiting, API key auth) | Compute Fabric | Tunnel | Public endpoint |
| Multi-device mesh (laptop discovers desktop via Tailscale network) | Compute Fabric | Tunnel | Personal mesh |
| Next.js web dashboard (layout, nav, responsive, accounts) | Frontend | Phase 1 dashboard | Full web UI |
| Auth system (signup, login, JWT, API keys) | Backend | Dashboard | User accounts |
| Cloud-hosted dashboard with history (paid tier feature) | Frontend | Auth + cost tracking | Cloud dashboard |

### Week 9-10: Full Router + vLLM + LAN
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Three-tier router production deploy (kNN + ModernBERT + Qwen-0.5B) | Conductor | Phase 1 prototypes + data | Full intelligent routing |
| Qwen2.5-0.5B Tier 3 reasoning router (Ollama multi-model loading) | Conductor | Router | Edge case handling |
| vLLM opt-in integration (continuous batching, prefix caching, throughput comparison) | Compute Fabric | Auth | Power user upgrade |
| LAN node discovery (mDNS) | Compute Fabric | Multi-device | LAN pooling |
| exo LAN cluster integration | Compute Fabric | LAN discovery | Multi-GPU LAN |
| Network topology mapping (latency per node type) | Compute Fabric | Multi-device + LAN | Latency-aware routing |

### Week 11-12: Intelligence + Preferences
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| User preference profiles (model prefs, cost sensitivity, privacy settings) | Frontend | Auth | Preferences saved |
| Feedback system (thumbs up/down, quality ratings -> router retraining) | Frontend | Auth + router | Feedback loop |
| Privacy classification router (PII detection via ModernBERT signals) | Conductor | ModernBERT | Privacy enforced |
| Advanced cache management UI (per-tier stats, namespace browser) | Caching | Dashboard | Cache visible |
| GPU memory management (VRAM tracking per model, OOM prevention) | Compute Fabric | Multi-device | Memory managed |

### Week 13-14: Monetization
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Stripe integration (Pro $19/mo, flat subscription, no credits) | Backend | Auth | Payments work |
| Feature gating (Free: 1 device; Pro: 5 devices + cloud dashboard + global router) | Backend | Stripe | Gates enforced |
| Pro upgrade prompts (at tunnel setup, in dashboard, feature locks) | Frontend | Gating | Conversion funnel |
| Pricing page (Free / Pro $19 / Team $49 / Enterprise $50, all self-serve) | Frontend | Stripe | Pricing visible |

### Critical Path: Tunnel -> Multi-device -> Full router -> Auth -> Stripe -> Pro launch
### Revenue Target: 200 Pro subscribers ($3,800/mo MRR)
### Resource Needs: 1-2 developers, Stripe account, $0 tunnel infrastructure (user's Tailscale/Cloudflare)

---

## PHASE 3: THE HIVE (Weeks 15-24) — IN PROGRESS

### Already Completed (10 issues closed)

**Hive Infrastructure (merged):**
- ~~Headscale deployed and running (port 8080, API key stored)~~ *Deprecated; replaced by self-hosted Rust relay (ADR-009)*
- ~~Hive ↔ Headscale integration (users + pre-auth keys) (#148)~~ *Deprecated; relay handles device auth natively*
- Node sharing controls (per-node toggle, schedule) (#149)
- Karma system wiring (compute contributed vs consumed) (#150)
- ~~Headscale ACLs (per-Hive access control) (#151)~~ *Deprecated; relay enforces access control via Noise NK + JWT*

**GPU-as-API MVP (PR #229 — in review):**
- `llmhosts up` unified command: serve + tunnel + auth + register (#223)
- OAuth 2.0 Device Code Flow for CLI auth, RFC 8628 (#224)
- Device registration, heartbeat, and health endpoints (#225)
- Remote device routing in relay (#226)
- API key bridge: proxy validates frontend-issued keys (#227)
- Comprehensive technical + marketing documentation (#228)

### Week 15-16: Hive Mode Core
| Task | Epic | Dependencies | Output | Status |
|------|------|-------------|--------|--------|
| ~~Headscale deployment~~ → Self-hosted Rust relay (ADR-009) | Security | Auth | Mesh for Hive | **DEPRECATED** → relay |
| Hive account system (create Hive, invite friends via link/code) | Hive Mode | Relay (was Headscale) | Hives created | **DONE** |
| Node sharing controls (per-node toggle, schedule) | Hive Mode | Hive + agent | Sharing works | **DONE** |
| Karma system (compute contributed vs consumed) | Hive Mode | Hive + routing | Karma tracked | **DONE** |
| Privacy-tiered routing for Hive (PII -> local only, standard -> Hive eligible) | Hive Mode | Router + privacy | Privacy enforced | **DONE** |
| ~~Headscale ACLs~~ → Relay access control (Noise NK + JWT) | Security | Hive + Relay (was Headscale) | Access controlled | **DEPRECATED** → relay |

### GPU-as-API MVP (added post-v3.0)
| Task | Epic | Dependencies | Output | Status |
|------|------|-------------|--------|--------|
| `llmhosts up` unified command (serve + tunnel + auth + register) | Onboarding | Phase 2 tunnel + auth | Single command to cloud API | **DONE** (#223) |
| OAuth 2.0 Device Code Flow (RFC 8628) | Security | Web dashboard auth | CLI authenticates with LLMHosts.com | **DONE** (#224) |
| Device registration + heartbeat + health endpoints | Backend | Auth + Prisma | Devices tracked in DB | **DONE** (#225) |
| Remote device routing in relay | Backend | Device registration | API calls forwarded to user's GPU | **DONE** (#226) |
| API key bridge (proxy validates frontend-issued keys) | Security | API keys + relay | CLI ↔ cloud key interop | **DONE** (#227) |
| Technical + marketing documentation | Docs | All above | Guides, architecture docs, landing copy | **DONE** (#228) |

### Week 17-18: Team + Gamification
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Team accounts ($49/seat/mo, Stripe, RBAC, admin controls) | Backend | Hive Mode | Teams active |
| Team dashboard (shared savings, node fleet, per-member usage) | Frontend | Team accounts | Team visible |
| Achievement system (badges, milestones, streaks) | Frontend | Auth + cost tracking | Badges earned |
| npx scaffolder (`npx create-llmhosts`, generates docker-compose + config) | Onboarding | Docker image | JS/TS onboarding |

### Week 19-20: Enterprise + Admin
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Enterprise self-serve ($50/user/mo, SOC2 docs, SLA, audit logs) | Backend | Team tier | Enterprise live |
| SSO/SAML integration | Security | Enterprise | SSO works |
| Admin dashboard (support tickets, user management, system health) | Frontend | Auth | Admin panel |

### Week 21-22: Email + Operations
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Email infrastructure (Zoho Mail Free, DNS records) | Email & Ops | GoDaddy DNS | Email working |
| AI auto-reply (support@ classify -> respond/escalate) | Email & Ops | Email | Auto-reply live |
| Transactional emails (signup, billing, alerts) | Email & Ops | Email | Transactional works |

### Week 23-24: Public Launch
| Task | Epic | Dependencies | Output |
|------|------|-------------|--------|
| Landing page ("Your hardware. Real AI infrastructure. From anywhere.") | Frontend | All above | Landing live |
| ProductHunt, HackerNews Show HN | Growth | Landing | Launches |
| Discord community | Growth | -- | Community |
| Blog: "My 4090 at home serves my laptop at a coffee shop" | Growth | Real data | Blog published |

### Critical Path: Self-hosted Rust relay (ADR-009) -> Hive Mode -> Team -> Enterprise -> Email -> Landing -> Launch
### Revenue Target: $10K+ MRR (1,000+ users across tiers)
### Resource Needs: 1-2 developers, relay embedded in existing infra (no separate VPS), marketing effort

---

## PHASE 4: INTELLIGENCE (Weeks 25-36) -- Summary

- W25-28: Global router intelligence (aggregate anonymized data, train global kNN + fine-tune ModernBERT)
- W29-32: Assisted model discovery (auto-benchmark new models, suggest to users)
- W33-36: Advanced caching (cross-user semantic dedup, GenCache for agentic workflows), K3s if needed

---

## RISK REGISTER

| ID | Risk | Probability | Impact | Mitigation | Owner |
|----|------|-------------|--------|------------|-------|
| R1 | Tiered pip install complexity | Medium | Medium | CI tests all tiers; Docker zero-config | DevOps |
| R2 | Three-tier router VRAM conflicts with inference | Low | High | VRAM budget math proven; Tier 3 CPU fallback | ML |
| R3 | Low adoption (<500 installs) | Medium | High | Open source + HN/Reddit + tunnel demo | Growth |
| R4 | `llmhosts tunnel` depends on external tools | Medium | Medium | Both free+reliable; guide install; fallback between | Infra |
| R5 | vCache false positive >1% in production | Low | High | Formal guarantee; entity namespace; monitoring | ML |
| R6 | Free-to-paid conversion <2% | Medium | High | Cloud dashboard has standalone value; tunnel drives Pro | Product |
| R7 | "Just an Ollama wrapper" | Medium | Medium | Tunnel + intelligence + vCache are novel | Marketing |
| R8 | Cloud GPU prices drop | Low | Medium | Access + privacy + latency are price-immune | Strategy |
| R9 | Tailscale/Cloudflare change free tier limits | Low | Medium | Both have generous free; alternative detection | Infra |
