# Design Principles

> These principles govern every design decision. When in doubt, defer to these.

## The 6 Principles

### 1. Zero Toil
The user types one command. Everything else is automatic.

- `llmhosts up` discovers hardware, installs engines, pulls models, starts proxy, connects tunnel, registers device
- No config files to write, no ports to configure, no DNS to manage
- If something needs user input, we're doing it wrong

### 2. Adaptive
Detects and adjusts for any environment condition.

- Windows port squatting → connect-based detection + IPv6 bridge
- No Ollama → auto-install + pull optimal model for detected VRAM
- Apple Silicon → 4GB VRAM offset for unified memory
- Corporate firewall → WSS relay (looks like HTTPS)
- Multiple GPUs → use max(VRAM) not sum

### 3. Resilient
Proxy always starts, even if subsystems fail.

- No internet → local proxy works
- No tunnel → device registers when internet returns
- No engine → clear error, doesn't crash proxy
- Port conflict → auto-finds next available
- Relay disconnect → auto-reconnect with exponential backoff

### 4. Private
Your data stays on your hardware by default.

- PII detection before external API routing (IslandRun)
- Tiered trust: personal=1.0, private=0.7, external=0.4
- Zero-knowledge relay (Noise NK encryption in active development — ships in relay M2)
- Dashboard shows "Stayed on YOUR machine" vs "Routed externally"

### 5. GPU Respect
Never interfere with user's GPU workloads. Passive monitoring only.

- Discovery is read-only (never modify engine state)
- No background GPU tasks the user didn't request
- Uninstall never removes engines or models
- If user is gaming or training → LLMHosts stays out of the way

### 6. Progressive Enhancement
Local first, tunnel optional, cloud fallback paid.

- Phase 1: localhost proxy (always works)
- Phase 2: relay tunnel (if authenticated)
- Phase 3: marketplace routing (if opted in)
- Every layer is optional; removing any layer degrades gracefully

---

## Brand Values (from `.hive/soul.md`)

| Value | Meaning |
|-------|---------|
| **Transparency** | Show the user exactly what's happening (routing decisions, costs, data flow) |
| **Humility** | Admit limits, suggest alternatives, never oversell |
| **Persistence** | Keep trying (reconnect, retry, fallback) without burdening the user |
| **Adaptability** | Handle any environment without manual intervention |
| **Developer empathy** | Respect the developer's time, tools, and workflows |

## Tone

- Concise, technical, evidence-backed
- No marketing fluff in CLI output
- Show data, not adjectives
- "$0.00" is more compelling than "save money"

---

## Core Value Proposition

**"Your hardware. Real AI infrastructure. From anywhere."**

One-liner: LLMHosts turns your GPU into an AI cloud you can access from any device.

The "holy shit" moment: Realizing your home GPU works from a coffee shop. Cost: $0.
