# Epic: Hive Mode (GPU Pooling Feature)

> **NAMING NOTE**: This epic covers **Hive Mode** -- the Phase 3 user-facing social GPU pooling feature. For the **Hive.CEO** embedded self-aware agent system (self-improvement, self-healing, admin panel), see `epic-hive-ceo.md`.

## DESCRIPTION
Social compute sharing: friends create "Hives," selectively share GPU nodes, benefit from collective compute. Karma system ensures fairness. Privacy-tiered routing prevents sensitive data from leaving owner's machine. Whole-model routing only (no WAN tensor sharding).

**POST-PIVOT (2026-02-14)**: Added karma system (BitTorrent model), privacy-tiered routing, whole-model WAN routing (not tensor sharding). Replaced OpenZiti with Headscale ACLs. Pro-tier only (key free→paid conversion trigger).

## RELATED DOCS
- docs/knowledge-base/hive-mode.md
- docs/knowledge-base/hive-intelligence.md

## BACKLOG ITEMS

### HM-001: Hive Account System
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Create Hive (group), invite friends via email/link, accept/decline invitations. Owner has admin privileges. Pro-tier required.
- **Acceptance**: `llmhosts hive create "My Hive"` → invite link generated. Web UI alternative. Friends join with link.
- **Dependencies**: FE-012 (Auth), Pro tier

### HM-002: Node Sharing Controls
- **Priority**: P0
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Per-node toggle: share on/off. Resource limits ("share up to 80% GPU"). Schedule ("share after 10pm weekdays, all day weekends").
- **Acceptance**: Node agent enforces sharing settings locally (cannot be overridden by Hive admin). Dashboard shows sharing status.
- **Dependencies**: HM-001, CF-001

### HM-003: Karma System
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Track compute contributed vs consumed per Hive member. BitTorrent-style ratio. High contributors get priority routing (lower latency, first in queue). Low contributors get deprioritized (not blocked).
- **Acceptance**: Karma ratio visible in Hive dashboard. High-karma members measurably get faster responses. No monetary accounting -- this is "friends sharing."
- **Dependencies**: HM-001, CB-003 (cost tracking)

### HM-004: Privacy-Tiered Routing
- **Priority**: P0
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Requests classified: PRIVATE (PII, user-flagged sensitive) → NEVER leave owner's nodes. STANDARD (code completion, general knowledge) → eligible for Hive routing. User controls per-category.
- **Acceptance**: Sensitive requests stay local. Dashboard shows "Stayed on YOUR machine" vs "Routed to Hive node (encrypted)." User controls sensitivity rules.
- **Dependencies**: CB-010 (privacy router), SEC-005 (PII detection)

### HM-005: Whole-Model WAN Routing
- **Priority**: P0
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Hive routing across WAN sends FULL REQUESTS to remote nodes (not tensor shards). Remote node runs model locally, returns response. 50ms WAN overhead per request is acceptable.
- **Acceptance**: Request routed to Hive member's node → complete response returned. No tensor sharding. Latency within 100ms of local inference + WAN RTT.
- **Dependencies**: CF-010 (Headscale WAN), CF-013 (Hive compute routing)

### HM-006: Headscale ACL Management
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Headscale ACL rules gate inter-user node access. Hive membership → ACL access. Leave Hive → ACL revoked.
- **Acceptance**: Only Hive members' nodes can communicate. ACLs enforced at WireGuard level.
- **Dependencies**: SEC-006, HM-001

### HM-007: Usage Attribution
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Track compute usage per Hive member: GPU-hours contributed, requests consumed, whose node served what.
- **Acceptance**: Hive dashboard shows per-member compute contributed vs consumed.
- **Dependencies**: HM-001, CB-003

### HM-008: Hive Dashboard
- **Priority**: P1
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Hive-specific views: members, shared nodes, karma scores, aggregate compute, group savings.
- **Acceptance**: Hive admin and members see shared compute pool, individual karma ratios, group savings.
- **Dependencies**: HM-001, HM-003, HM-007, FE-016

### HM-009: Hive Gamification
- **Priority**: P2
- **Phase**: 3
- **Status**: BACKLOG
- **Description**: Hive-specific badges: "Hive Founder," "Generous Node" (100+ GPU-hours contributed), "First Hive Inference." Group milestones.
- **Acceptance**: Badges visible on Hive dashboard. Contribution leaderboard. Group celebration on milestones.
- **Dependencies**: HM-007, FE-015
