# User Success Journeys

> Every journey ends with: "It just works." No exceptions.

---

## Journey 1: First Install (Windows, RTX 4090)

**User**: Developer with Alienware laptop, RTX 4090, Cursor IDE running.

**Steps**:
```powershell
irm https://llmhosts.com/install.ps1 | iex
llmhosts up
```

**What happens automatically** (zero user input after install):
1. **Python detection** -- finds Python or installs uv (Rust-based, 10-100x faster than pip)
2. **Engine discovery** -- detects Ollama running, finds qwen3:32b loaded
3. **Port detection** -- port 11400 taken by Cursor IDE? Auto-scans to 11401, 11402...
4. **Binding strategy** -- binds `127.0.0.1:PORT` (specific) to prevent Cursor squatting
5. **IPv6 bridge** -- claims `[::1]:PORT` before Cursor can squat IPv6 loopback
6. **HTTP parser** -- detects Windows, uses h11 (pure Python) instead of httptools (C extension that silently fails on Windows)
7. **Device auth** -- browser opens, user logs in, device code verified
8. **Device registration** -- registers even without tunnel (dashboard shows it)
9. **Heartbeat** -- 30-second heartbeat to llmhosts.com, auto-creates device record if needed
10. **Proxy starts** -- OpenAI-compatible API at `http://localhost:PORT`

**What the user sees**:
```
Phase 1: Discovering inference engines...
  Ollama at localhost:11434 -- 1 model (qwen3:32b)

Phase 2: Analyzing hardware...
  NVIDIA GeForce RTX 4090 (24.0GB), 64GB RAM

Phase 3: Connecting to LLMHosts.com...
  Device registered as "ALIENWARE-R16"

Phase 4: Starting proxy...
  API ready at http://localhost:11402

Set these env vars to use from any tool:
  OPENAI_BASE_URL=http://localhost:11402/v1
  OPENAI_API_KEY=lh_sk_...
```

**Verified**: 2026-03-08, Windows 11, Cursor IDE active on 17+ ports including 11400.

---

## Journey 2: First Install (macOS, Apple Silicon)

**User**: Designer with MacBook Pro M3 Max, 96GB RAM.

**Steps**:
```bash
curl -fsSL https://llmhosts.com/install.sh | sh
llmhosts up
```

**What happens automatically**:
1. uv installs llmhosts in an isolated environment
2. No Ollama found -- auto-installs Ollama, pulls optimal model for 96GB RAM
3. Apple Silicon detected -- 4GB VRAM offset applied (unified memory sharing)
4. No port conflicts -- binds 11400 directly
5. Auth, registration, proxy start

**Expected first-run time**: ~3 minutes (mostly model download).

---

## Journey 3: Cursor IDE Power User

**User**: Full-stack developer, Cursor IDE as primary editor, wants local AI.

**Challenge**: Cursor IDE aggressively binds ports. On Windows, it watches for new services and squats both `127.0.0.1:PORT` and `[::1]:PORT`, hijacking `localhost` traffic.

**How LLMHosts handles it**:
1. **Connect-based port detection** -- probes both IPv4 AND IPv6 loopback (not bind-based, which lies on Windows)
2. **Specific binding** -- `127.0.0.1` instead of `0.0.0.0` (Windows routes specific > wildcard)
3. **IPv6 bridge** -- TCP relay on `[::1]:PORT` forwarding to `127.0.0.1:PORT`
4. **Adaptive scanning** -- if preferred port taken, scans +100 ports upward
5. **Result**: `curl http://localhost:PORT/health` always works, even with Cursor active

**User configures Cursor**:
```json
{
  "openai.apiBase": "http://localhost:11402/v1",
  "openai.apiKey": "lh_sk_..."
}
```

**Verified**: 2026-03-08. Cursor squatting 17+ ports including default 11400. LLMHosts auto-selected 11402, held both IPv4 and IPv6.

---

## Journey 4: Multi-Machine Developer

**User**: Has RTX 4090 at home, MacBook for travel, wants same API from both.

**Steps on home machine**:
```bash
llmhosts up
# GPU is now accessible from anywhere
```

**Steps on MacBook (or any device)**:
```bash
export OPENAI_BASE_URL=https://your-device.llmhosts.com/v1
export OPENAI_API_KEY=lh_sk_...
# Every OpenAI-compatible tool now uses your home GPU
```

**What works transparently**: LangChain, Continue, Aider, custom Python scripts, curl, any OpenAI SDK client. Change two env vars, everything routes to your GPU.

---

## Journey 5: Team / Small Company

**User**: 5-person startup, 3 GPUs across team members' desks.

**Steps**:
1. Each team member runs `llmhosts up` on their GPU machine
2. Team lead creates a Hive: `llmhosts hive create "startup-ai"`
3. Members join: `llmhosts hive join <invite-code>`
4. Requests auto-route to the best available GPU (karma-weighted)
5. Privacy controls: PII stays local, shared prompts route across Hive

**Cost savings**: 3x RTX 4090s at $0/month vs. $600/month on OpenAI API.

---

## Journey 6: Graceful Degradation

**User**: Any user. Internet goes down, tunnel fails, engine crashes.

**What LLMHosts does**:
- **No internet**: Proxy still runs locally. All local inference works.
- **No tunnel**: Device still registers via heartbeat when internet returns. Dashboard shows device status.
- **No Ollama**: Auto-provisions Ollama + starter model on first run. If Ollama crashes mid-session, proxy returns clear error, doesn't crash itself.
- **Port conflict**: Auto-finds next available port. Never fails to start.
- **VRAM insufficient**: Suggests smaller model, pulls it automatically.

**Principle**: The proxy ALWAYS starts. Everything else is progressive enhancement.

---

## Journey 7: Marketplace Operator (Pro Plan)

**User**: Has 3x RTX 4090 workstation, wants to earn from spare GPU cycles.

**Steps**:
1. `llmhosts up` -- GPUs discovered and registered
2. Dashboard: toggle "List on Marketplace"
3. Set price (e.g., $0.50/1M tokens)
4. Buyers find the node, route requests, operator earns 80% (platform 20%)

**Auto-removal**: Nodes with <30% uptime over 30 days are automatically delisted. No marketplace pollution. Reputation score tracks reliability.

---

## Edge Cases Handled (Learned from Real E2E Testing)

| Edge Case | Solution |
|-----------|----------|
| Cursor IDE squats ports | Connect-based detection + specific binding + IPv6 bridge |
| Windows `localhost` = `::1` | IPv6 TCP bridge forwards to real IPv4 server |
| `httptools` fails on Windows | Auto-detect Windows, use `h11` (pure Python) |
| Tunnel fails, heartbeat 500s | Upsert device record on heartbeat (not just update) |
| Device registered without tunnel | Registration no longer requires tunnel_url |
| Port 11400 pre-occupied | Adaptive scan: 11400 -> 11401 -> 11402 -> ... |
| No inference engine found | Auto-install Ollama + pull model for detected VRAM |
| VRAM too small for chosen model | Suggest smaller model from VRAM tier map |
| Multiple GPUs, VRAM calc wrong | Use max(GPU VRAM) not sum (multi-GPU VRAM fix) |
| Apple Silicon unified memory | 4GB offset applied (OS reserves from unified pool) |

---

## Design Principles

1. **Zero toil** -- the user types one command. Everything else is automatic.
2. **Adaptive** -- detects and adjusts for any environment condition.
3. **Resilient** -- proxy always starts, even if subsystems fail.
4. **Private** -- your data stays on your hardware by default.
5. **GPU respect** -- never interferes with user's GPU workloads. Passive monitoring only.
6. **Progressive enhancement** -- local first, tunnel optional, cloud fallback paid.
