Skip to content

README.md

Latest commit

 

History

History
134 lines (89 loc) · 5.53 KB

README.md

File metadata and controls

134 lines (89 loc) · 5.53 KB
Raw

Herdr Connect

简体中文

Control your Herdr agents from your iPhone — with no cloud in between.

Herdr Connect — LAN Discovery Demo

Herdr Connect is a companion app for Herdr. See what every agent is doing, read their latest output, send a follow-up, and get a nudge when a job finishes — while your data stays on your own network.

Agent list Agent detail Settings

Why Herdr Connect

  • See everything at a glance — every agent's status, workspace, and recent activity in one list
  • Stay close to the work — read output, send instructions, or interrupt a running turn
  • Know when it's done — sound, haptic, and notification cues when an agent finishes
  • Private by design — the phone talks directly to your daemon over the local network. No cloud relay, no accounts, no telemetry

Requirements

  • A computer running Herdr with at least one agent
  • An iPhone (Android is not yet available)
  • Both devices on the same network — your Wi-Fi at home, or a VPN such as Tailscale that puts them on the same virtual LAN

Quick start

  1. Make sure Herdr is installed and has at least one agent:

    herdr agent list

  2. Install the daemon on the computer running Herdr (the download needs no Go, Node.js, or Xcode):

    curl -fsSL https://raw.githubusercontent.com/Tomyail/herdr-connect/main/install.sh | sh

    On Windows, download and extract the zip from the Releases page instead.

  3. Start it:

    ~/.local/bin/herdr-connect doctor
~/.local/bin/herdr-connect service install

  4. Install the iOS app via the Herdr Connect TestFlight beta and allow Local Network access when prompted.

  5. Pair your phone. This prints a one-time QR code — scan it from the app's Settings → Pair new device:

    herdr-connect pair

  6. Open the Agents tab. Tap an agent to view its output, send messages, or interrupt it.

Something not connecting? Check that both devices are on the same network, pause VPNs that block local multicast, and look at firewall or guest-network isolation settings. The daemon guide and TestFlight troubleshooting cover the details, and the CLI guide documents every command.

How it works

Herdr CLI
    │
Herdr Connect daemon   ← runs on your computer
    │
iPhone app             ← pairs, then talks to the daemon directly

The daemon and the app find each other on the local network. Trust is established once, by scanning a QR code from the pairing command; after that the phone only accepts the daemon it paired with. For the full trust model and its current limits, see LAN TLS and pairing.

Project status

Area Status
iOS app Public TestFlight beta
Discovery, pairing, secure transport Implemented
Agent list, output, focus, messaging, interrupt Implemented
Android Not yet published
Off-network remote access (relay + E2EE) Future milestone

FAQ

Can I use it away from home? Not with an official relay — that is a future milestone. If you already run a mesh VPN like Tailscale, the app works fine across it as long as the phone can reach the daemon; you are responsible for the VPN's security.

Does my data go to a server? No. The app talks directly to the daemon on your network. There is no cloud relay and no account system.

Which Herdr versions are supported? The app and daemon negotiate versions and will prompt you to upgrade when they don't match. See the daemon guide.

Documentation

Audience Start here
Install and pair Quick start, daemon guide, TestFlight troubleshooting
CLI reference CLI guide
Security model LAN TLS and pairing
Architecture and contributor docs OpenWiki

Develop from source

Setup, repository layout, and the full workflow live in OpenWiki: development setup, testing guide.

corepack enable
pnpm install --frozen-lockfile
pnpm demo:lan      # run a local daemon on TCP 9808
pnpm ios:mobile    # Expo development build on a physical iPhone

The app needs native modules (mDNS, pinned TLS, camera, notifications), so use an Expo development build, not Expo Go.

Security

Do not report vulnerabilities or sensitive data in public issues — follow SECURITY.md.

Contributing

Bug reports, reproducible discovery or pairing failures, and design feedback are welcome in GitHub Issues. Please read CONTRIBUTING.md first.

Relationship to Herdr

Herdr Connect is an independent companion project, not affiliated with or endorsed by the Herdr project. Herdr is installed separately and remains subject to its own license.

License

Licensed under the Apache License 2.0.