Install the bridge

Requirements#

• Computer
  macOS on Apple silicon or Intel, or Linux on x86-64 or ARM64. It must stay awake while you use the phone.
• Terminals
  Herdr, Orca, or nothing: the plain backend runs its own shells.
• macOS
  Nothing else. Allow incoming connections and local network access when asked.
• Linux
  openssl for the first start, and avahi-utils (avahi-publish) so phones on your Wi-Fi can find the computer.
• Network
  The phone on the same network, on your VPN, or a relay you run. See Reach it from anywhere.

Install#

One command

curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | sh

brew tap crow-tech-pte-ltd/agent-remote-bridge https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridgebrew install agent-remote-bridge

cd ~unzip ~/Downloads/agent-remote-bridge-*-macos-*.zip   # creates ~/agent-remotecd ~/agent-remotexattr -dr com.apple.quarantine .   # macOS blocks downloaded programs otherwise./herdr-remote up

cd ~unzip ~/Downloads/agent-remote-bridge-*-linux-*.zip   # creates ~/agent-remotecd ~/agent-remote./herdr-remote up

docker pull ghcr.io/crow-tech-pte-ltd/agent-remote-bridge:latest

If you keep the kit in ~/agent-remote, run it as ./herdr-remote from that folder, or add the folder to your PATH. The rest of these docs write plain herdr-remote.

First start#

herdr-remote up

up is the one-step command for a computer on your Wi-Fi. On first run it creates the private state directory ~/.local/share/herdr-remote (folder mode 0700, files 0600) with a self-signed certificate for this computer’s .local name and network addresses, then serves on port 8443, advertises the computer to phones nearby and opens the web console. Next time it reuses the same state, so paired phones reconnect without asking.

• --backend herdr|orca|plain
  Which terminals to serve. Herdr is the default; the choice is remembered.
• --folder DIR
  Plain backend: a folder to open as a workspace (repeatable). Default: your home folder.
• --herdr PATH
  Where the herdr program is, if it is not on the bridge’s PATH.
• --port 8443
  Port for phones on first start.
• --name NAME
  Name shown on the phone (default: the computer’s name).
• --no-discovery
  Don’t advertise or accept nearby pairing; already-paired phones still connect.
• --no-console
  Don’t start the local web console.
• --state DIR
  Use another private state directory, for example to run a second bridge.

Prefer explicit settings? herdr-remote init then herdr-remote serve gives you full control over the address, listener and certificate names; see the CLI reference.

Keep it running#

The bridge serves phones only while it runs. The simplest way is a Herdr tab. To start it with your login instead:

Linux: systemd user service

The Linux kit includes herdr-remote.service, which runs ~/agent-remote/herdr-remote up. Edit ExecStart if you put the kit elsewhere.

mkdir -p ~/.config/systemd/usercp ~/agent-remote/herdr-remote.service ~/.config/systemd/user/systemctl --user enable --now herdr-remotejournalctl --user -u herdr-remote -f     # follow its log

To keep a user service running after you log out, enable lingering once with loginctl enable-linger "$USER".

macOS: LaunchAgent

The bridge repository has a LaunchAgent template, dev.herdr.remote.plist.example. Replace the paths with your kit and state folder, save it as ~/Library/LaunchAgents/dev.herdr.remote.plist, then:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.herdr.remote.plist

Update#

Stop the bridge, replace the herdr-remote program with the one from the new kit (or run brew upgrade agent-remote-bridge), and start it again. Your state directory, certificate and paired phones stay as they are. Phone features that need a newer bridge simply stay hidden until you update it.

Uninstall#

systemctl --user disable --now herdr-remote   # if you installed the Linux servicerm -rf ~/agent-remote                          # the programrm -rf ~/.local/share/herdr-remote             # its state: certificate and paired phones

Removing the state directory unpairs every phone. On each phone, swipe the computer in Connections and choose Forget to remove its saved credential too.

Run from source#

With Bun 1.3.9 or later and OpenSSL installed:

git clone https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge.gitcd agent-remote-bridge/serverbun install --frozen-lockfilebun src/cli.ts up

bun build src/cli.ts --compile --outfile herdr-remote makes the same single-file program the kits contain.