# ADR-004: Security & Networking Overlay

## STATUS
PARTIALLY SUPERSEDED (2026-03-08) -- Phase 2 & 3 networking replaced by ADR-009 (self-hosted relay). Privacy routing (application layer) unchanged.

## CHANGE LOG
- 2026-02-13: Original proposal -- OpenZiti full zero-trust overlay + IslandRun privacy routing
- 2026-02-14 (pivot): SUPERSEDED -- pivoted to Headscale/WireGuard for all networking
- 2026-02-14 (course correction): **REVISED** -- tiered networking. Phase 1: localhost only. Phase 2: `llmhosts tunnel` auto-detects Tailscale or Cloudflare Tunnel for personal remote access. Phase 3: Headscale for Hive Mode coordination only.
- 2026-03-08: **PARTIALLY SUPERSEDED** by [ADR-009](adr-009-relay-tunnel.md). Self-hosted Rust relay replaces Tailscale/Cloudflare as primary tunnel provider. Tailscale/Cloudflare retained as fallback only. Headscale deprecated entirely. Privacy routing unchanged.

## CONTEXT
LLMHosts core value prop: **"your hardware becomes real AI infrastructure accessible from anywhere."** People have GPUs at home and NO clean way to use them from their laptop at a coffee shop, phone, or CI pipeline. The networking layer transforms "local tool" into "personal AI cloud."

### Why the Pivot Over-Corrected
The initial pivot moved ALL networking to Headscale. But Headscale is overkill for personal remote access:
1. Tailscale (free, 100 devices) already does personal device mesh
2. Cloudflare Tunnel (free unlimited) does zero-config public HTTPS
3. Most users need "access my home GPU from my laptop," not "run a mesh network"
4. `llmhosts tunnel` auto-detecting what is available IS the transformative UX

### The Viral Moment
`llmhosts tunnel` then "My 4090 at home is serving inference to my laptop right now. Cost: $0." NOBODY has built the "one install, your GPU works from anywhere" product. Market is wide open.

## OPTIONS EVALUATED (REVISED)

### Option A: OpenZiti -- DEFERRED (Phase 4+ enterprise)
- Full zero-trust, identity-based networking
- Operationally heavy for startup
- Upgrade path for enterprise

### Option B: Tailscale (User's Own) -- PHASE 2 AUTO-DETECT
- `tailscale funnel 4000` = public HTTPS URL in one command
- Free for 100 devices
- 10-80ms added latency (irrelevant for LLM text streaming)
- No infrastructure to run
- Best for: Users who already have Tailscale

### Option C: Cloudflare Tunnel -- PHASE 2 AUTO-DETECT
- 15-minute setup, free unlimited tunnels
- Zero-trust auth with service tokens
- Best for: Users wanting public HTTPS endpoint for tools/CI

### Option D: Headscale (Self-Hosted) -- PHASE 3 HIVE ONLY
- Self-hosted Tailscale coordination
- 1 Docker container, WireGuard encryption
- Only needed for Hive Mode: coordinating GPU pools between different users

### Option E: HTTPS + mTLS -- PHASE 1 LOCAL
- Simplest: proxy on localhost:4000
- No overlay, no NAT traversal
- Phase 1 is single-machine

## DECISION
**Three-phase tiered networking**:

### Phase 1: Localhost Only (Weeks 1-6)
```
llmhosts serve -> localhost:4000
No networking complexity. Local proxy. Period.
mTLS for any cloud service communication.
```

### Phase 2: llmhosts tunnel -- Your GPU From Anywhere (Weeks 7-14)
```
llmhosts tunnel
  |
  +-- Detect Tailscale installed?
  |    YES -> tailscale funnel 4000
  |           Public HTTPS URL in 5 seconds
  |           Authenticated via Tailscale identity
  |
  +-- Detect Cloudflare Tunnel (cloudflared)?
  |    YES -> cloudflared tunnel --url localhost:4000
  |           Public HTTPS URL via Cloudflare
  |           Auth via service tokens
  |
  +-- Neither installed?
  |    "Install Tailscale (recommended) or Cloudflare Tunnel"
  |    One-liner install instructions per OS
  |    Auto-retry after install
  |
  +-- llmhosts tunnel --public
       Tailscale Funnel or Cloudflare Tunnel
       Creates shareable HTTPS URL for API access
       Rate-limited, API key required
```

The user never chooses a tunneling technology. `llmhosts tunnel` detects and does the right thing.

### Phase 3: Hive Mode Coordination (Weeks 15-24)
```
llmhost hive join <code>
  Headscale coordination for multi-user GPU pooling
  ACL policies manage inter-user access
  WireGuard encrypted tunnels between Hive members
  Only needed for sharing compute with OTHER people
```

### Privacy Routing (Application Layer -- All Phases)
```
Request Classification:
  PRIVATE: PII detected, user-flagged sensitive, personal/legal/medical
    Routes ONLY to user own nodes or cloud APIs under user keys
  STANDARD: Code completion, general knowledge, public information
    Eligible for Hive routing to trusted friend nodes
  User controls classification rules per category
  Dashboard: "Stayed on YOUR machine" vs "Routed to Hive (encrypted)"
```

## RATIONALE
- Phase 1 needs ZERO networking -- just localhost proxy. Maximum simplicity.
- Phase 2 leverages EXISTING tools (Tailscale/Cloudflare) users may already have. No infra to run. Free tier covers all personal use.
- `llmhosts tunnel` auto-detection is the key UX innovation
- Tailscale Funnel: one command, public HTTPS. Latency 10-80ms (irrelevant for LLM streaming).
- Cloudflare Tunnel: free, unlimited, excellent zero-trust auth.
- Headscale reserved for Phase 3 Hive Mode only.
- Privacy routing stays at application layer (works regardless of networking layer).
- "Your 4090 at home serving your laptop at a coffee shop" is the viral screenshot moment.

## CONSEQUENCES
- Users need Tailscale or Cloudflare Tunnel installed for Phase 2 (both free, easy install)
- Dependent on Tailscale/Cloudflare availability (mitigated: both are massive, reliable services)
- Headscale infra only needed for Phase 3 Hive Mode (self-funding via paid tier)
- No custom networking code in Phase 1-2 (delegate to established tools)
- Phase 3 Headscale adds operational cost (~$5/mo VPS) covered by Hive tier pricing
