| type | Project Overview | ||||||
|---|---|---|---|---|---|---|---|
| title | Herdr Connect | ||||||
| description | Local-first companion for Herdr that enables LAN discovery and control of AI agents from mobile devices | ||||||
| tags |
|
Herdr Connect is an experimental, local-first companion for Herdr that enables mobile devices to discover and interact with AI agents running on the same local network. All LAN communication is secured with TLS (self-signed certificate with fingerprint pinning) and per-device bearer tokens obtained through a QR-code pairing flow.
Herdr Connect consists of three main components:
- Go Daemon — A background service that communicates with the Herdr CLI, maintains a local projection of agent state, serves an HTTPS API with bearer-token auth, and advertises itself on the LAN via Bonjour/mDNS
- iOS Mobile Client — A React Native app that discovers the daemon, pairs via QR code, and interacts with agents (view output, switch focus, send text, interrupt)
- Protocol Package — TypeScript/Go cryptographic primitives for future end-to-end encryption over remote relay connections (research phase, not yet integrated)
The daemon runs as a persistent service on macOS/Linux and communicates with Herdr through its CLI interface, parsing JSON output to track agents without embedding or linking Herdr source code.
Herdr Connect is not:
- A production-ready remote access product
- A cloud service or account system
- An end-to-end encrypted communication channel (E2EE is planned for the relay milestone)
- A replacement for Herdr itself — it requires a separate Herdr installation
All LAN communication is encrypted with TLS (self-signed certificate with fingerprint pinning) and authenticated with per-device bearer tokens obtained through pairing. There is no end-to-end encryption layer yet — TLS terminates at the daemon.
Supported features:
- ✅ Bonjour/mDNS daemon advertisement as
_herdr-connect._tcp(with certificate fingerprint in TXT record) - ✅ TLS HTTPS server with self-signed certificate and SHA-256 fingerprint pinning
- ✅ QR-code pairing with one-time secret and per-device bearer tokens (
pair --hostselects a specific interface, e.g. for Tailscale pairing) - ✅ Device management: list paired devices, revoke devices (
herdr-connect devicesCLI) - ✅ Per-endpoint rate limiting (token bucket: reads, writes, pairing)
- ✅ Snapshot caching and coalescing (1-second TTL with singleflight)
- ✅ iOS discovery on physical devices (TestFlight beta available)
- ✅ Agent list display with status indicators
- ✅ View recent agent output (last 120 lines)
- ✅ Switch focus to an agent
- ✅ Send text input to an agent
- ✅ Interrupt a running agent
- ✅ Real-time status push via SSE for foreground UI freshness
- ✅ API version negotiation with daemon/app upgrade prompts
- ✅ Foreground local notifications, haptics, and completion chime on agent finish
- ✅ Localized UI (English and Chinese)
- ✅ Light/dark theme
Not yet implemented:
- ❌ Android app
- ❌ End-to-end encryption (HPKE-based protocol exists but is not yet integrated)
- ❌ Remote connections outside LAN (relay milestone)
- ❌ Remote push notifications (APNs/Expo Push)
Start here for project context, then explore specific areas:
- Architecture Overview — System components, data flow, security model, and design principles
- Herdr Source Adapters — How the daemon interfaces with Herdr CLI
- Agent Projection — State synchronization and persistence
- CLI Commands — Daemon management, pairing, device management, and diagnostics
- iOS Client — Mobile app structure, pairing flow, discovery, and interaction
- Secure Pairing & TLS Protocol — LAN pairing, TLS pinning, device lifecycle, and future E2EE design
- Development Setup — Build instructions and development workflow
- Testing Guide — Test suites and quality practices
- Source Repository: github.com/Tomyail/herdr-connect
- Upstream Herdr: github.com/ogulcancelik/herdr
- User Documentation:
/docs/directory (CLI guide, daemon guide, TLS & pairing security model at/docs/security/lan-tls-pairing.md) - Domain Language:
/CONTEXT.md(Chinese — defines project terminology)
When updating this documentation:
- Preserve the domain language from
/CONTEXT.md— use "owner", "installation", "device", "Agent" consistently - Link concepts, not just files — explain relationships between components before listing source paths
- Distinguish LAN security vs. relay roadmap — TLS + pairing is implemented today; end-to-end encryption and remote relay are future milestones
- Ground claims in source — reference specific Go/TS files when describing implementation details
- Keep sections focused — avoid duplicating content; link to canonical locations instead
Generated by OpenWiki.