Set up with an AI agent

You are helping me set up AI Agent Remote on this computer. Goal: the open-source bridge (`agent-remote`) installed and running here, my phone paired with the access I choose, the bridge kept running, and (if I want it) reachable when I am away from home. Work through the steps below one at a time and tell me what you are about to run. If something here doesn't match what you see, read the matching docs page (Markdown links at the end) before you improvise. ## Before you start, ask me 1. Is this computer macOS (Apple silicon or Intel) or Linux (x86-64 or ARM64)? Windows is not supported.2. Where do my agents run: Herdr, Orca, or plain shells? For plain shells, which project folders should become workspaces?3. How should you install the bridge: install script, Homebrew, or a release kit?4. Is my phone on the same Wi-Fi as this computer, and do I trust that network? (Café, hotel or office: pair with a QR invitation instead.)5. Should the phone get read access (watch only) or control access (type, start agents, close panes)?6. Should the bridge start with the computer (a service)?7. Do I need to reach it away from home? If so, through a VPN I already use (Tailscale, WireGuard or similar), a reverse relay on a server I run, or app-only WireGuard? ## Prerequisites - An iPhone or iPad on iOS 17 or later with AI Agent Remote installed (Android is coming soon).- My coding agents installed and signed in on this computer. The computer must stay awake while I use the phone.- Linux: `openssl` for the first start, `avahi-utils` (`avahi-publish`) so phones can find the computer, and TCP port 8443 allowed from my network if a firewall is on.- macOS: I will allow incoming connections and local network access when macOS asks. ## Steps 1. **Install the bridge.** Install script (installs to `~/.local/bin` without sudo, checks SHA-256 checksums, may add `~/.local/bin` to my `PATH`; open a new terminal afterwards, or set `AGENT_REMOTE_NO_MODIFY_PATH=1` to leave shell files alone). Offer to show it first with `curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | less`.    ```sh   curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | sh   ```    Or Homebrew:    ```sh   brew tap crow-tech-pte-ltd/agent-remote-bridge https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge   brew install agent-remote-bridge   ```    Or a release kit from https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/releases/latest (`agent-remote-bridge-VERSION-macos-arm64.zip`, `-macos-x64`, `-linux-x64` or `-linux-arm64`): unzip it in `~` (it creates `~/agent-remote`), run `xattr -dr com.apple.quarantine .` in that folder on macOS, and run `./agent-remote` from there. 2. **Start it.** With Herdr, run it in a Herdr tab, or pass `--herdr "$(which herdr)"`. Without Herdr or Orca, use the plain backend (the choice is remembered). On an untrusted network, add `--no-discovery`. Orca: initialise with `--backend orca --orca-connection FILE` as on the backends page (separate state directory and port if a Herdr bridge also runs).    ```sh   agent-remote up   agent-remote up --backend plain --folder ~/code/api --folder ~/code/web   ```    The first start creates `~/.local/share/herdr-remote`, listens on port 8443, advertises the computer nearby and opens the web console (`agent-remote console` prints a one-time link). 3. **Pair the phone, choosing read or control.**   - Nearby: in the app, under **On this network**, I tap **Pair**. A 6-digit code appears on this computer (notification, Herdr, and the terminal running `up`). Stop and let me type it and compare the fingerprint on both screens. These phones get the console's **Access for phones paired with a code** (control by default).   - QR invitation: ask me to run `agent-remote pair --scope control --qr` (or `--scope read`, the default) in a terminal only I can see, then scan it in the app with **Connect a computer**. It is valid for five minutes (`--ttl`) and works once. 4. **Keep it running.** Stop any bridge running in a terminal first, then install the service with the same options I gave `up`:    ```sh   agent-remote service install   # plus the options you gave up, e.g. --backend plain   agent-remote service status   ```    Linux: a systemd user service; `loginctl enable-linger "$USER"` starts it at boot without logging in. macOS: a LaunchAgent; services can't use Downloads, Desktop or Documents, so keep a kit in e.g. `~/Applications/agent-remote`, and keep the Mac from sleeping. 5. **Remote access (only if I asked for it).**   - My own VPN, new bridge: `agent-remote init --url https://100.101.102.103:8443 --listen 0.0.0.0 --port 8443` (this computer's VPN IP), then `agent-remote serve` and a fresh `pair --scope control --qr`. Existing bridge: `agent-remote address` shows what the certificate covers; `agent-remote address set ADDRESS` or `pair --url ADDRESS` for a covered address; otherwise a separate `--state` directory with `init`, and pair again. If the VPN reaches my home network, invitations from bridge 0.1.37 and later may already work.   - Reverse relay (one relay per bridge; iPhone and iPad only for now): on a server, `agent-remote relay serve --listen 127.0.0.1 --port 8788` behind HTTPS that forwards only `/v1/tunnel` and `/v1/host` with WebSocket upgrades. Then `agent-remote relay profile --public-url wss://relay.example.com > relay.json` and `chmod 600 relay.json`, copied privately (e.g. `scp`). On this computer: `agent-remote relay join relay.json`, restart the bridge, and pair again with a fresh QR invitation.   - App-only WireGuard: `agent-remote pair --scope control --qr --connection wireguard-route.json` (format: https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/blob/main/protocol/connection-routes.md), or I paste a WireGuard config while pairing. Give each phone its own peer. ## Verify - `agent-remote help` runs (it is on the `PATH`), and `up` reports that it is listening, with its address.- `agent-remote devices` lists my phone with the expected scope; the phone's **Projects** tab shows my workspaces.- `agent-remote service status` says installed and running; after a reboot or login, the phone reconnects by itself.- Relay: the bridge prints `relay_connected`, and `agent-remote relay status` shows the relay. Then test from the phone off Wi-Fi.- `agent-remote certificate` shows the fingerprint and expiry. ## Common pitfalls - Not under **On this network**: same Wi-Fi (not an isolating guest network), Local Network allowed for the app on the iPhone, no `--no-discovery`, avahi running on Linux. Otherwise pair by QR.- Fingerprints don't match: cancel; something else answered. Pair by QR on the computer itself.- "A bridge already owns this state directory": another bridge (perhaps the service) uses it. Stop it, or use its own `--state` and `--port`.- Herdr not found: services have a shorter PATH than your shell; pass `--herdr "$(which herdr)"`.- macOS won't open the kit: `xattr -dr com.apple.quarantine ~/agent-remote`.- Works at home only: `.local` names and 192.168… addresses aren't reachable elsewhere; set up a route above and pair again.- No `relay_connected`: restart after joining, check the proxy forwards both paths with WebSocket upgrades, set `HTTPS_PROXY` behind a corporate proxy (its root certificate in `NODE_EXTRA_CA_CERTS` if it inspects TLS).- Can watch but not type: paired read-only (pair again with `--scope control`), or another device controls the pane.- Logs: the terminal running the bridge; Linux service: `journalctl --user -u agent-remote -f`; macOS service: `service.log` in the state folder. ## Rules for you - Install without sudo. Don't pipe the install script into `sh` before offering to show it.- Treat pairing invitations, QR codes, `herdr-remote://pair` links, console links and relay profiles as secrets: never print them into this chat or logs. Let me run `agent-remote pair` myself.- Stop and wait for me whenever the phone or a system dialog is involved: typing the code, comparing fingerprints, scanning a QR code, macOS permission prompts.- Give control only to my own devices. Never try to turn off certificate checks.- Reach the bridge from outside only through the routes above. The console listens on 127.0.0.1 only; from another computer, use `ssh -L 8790:127.0.0.1:8790` and `agent-remote console`. With a reverse proxy on this same computer, leave nearby discovery off.- Don't delete `~/.local/share/herdr-remote`: that unpairs every phone. `init` never overwrites existing state. ## Full documentation - Overview: https://crow.sg/apps/ai-agent-remote/docs/ (Markdown: https://crow.sg/apps/ai-agent-remote/docs/index.md)- Quickstart: https://crow.sg/apps/ai-agent-remote/docs/quickstart/ (https://crow.sg/apps/ai-agent-remote/docs/quickstart.md)- Install the bridge: https://crow.sg/apps/ai-agent-remote/docs/install/ (https://crow.sg/apps/ai-agent-remote/docs/install.md)- Pair a phone: https://crow.sg/apps/ai-agent-remote/docs/pairing/ (https://crow.sg/apps/ai-agent-remote/docs/pairing.md)- Using the app: https://crow.sg/apps/ai-agent-remote/docs/using-the-app/ (https://crow.sg/apps/ai-agent-remote/docs/using-the-app.md)- Web console: https://crow.sg/apps/ai-agent-remote/docs/console/ (https://crow.sg/apps/ai-agent-remote/docs/console.md)- Web remote: https://crow.sg/apps/ai-agent-remote/docs/web-remote/ (https://crow.sg/apps/ai-agent-remote/docs/web-remote.md)- Reach it from anywhere: https://crow.sg/apps/ai-agent-remote/docs/remote-access/ (https://crow.sg/apps/ai-agent-remote/docs/remote-access.md)- Backends & agents: https://crow.sg/apps/ai-agent-remote/docs/backends/ (https://crow.sg/apps/ai-agent-remote/docs/backends.md)- Security: https://crow.sg/apps/ai-agent-remote/docs/security/ (https://crow.sg/apps/ai-agent-remote/docs/security.md)- CLI reference: https://crow.sg/apps/ai-agent-remote/docs/cli/ (https://crow.sg/apps/ai-agent-remote/docs/cli.md)- Troubleshooting: https://crow.sg/apps/ai-agent-remote/docs/troubleshooting/ (https://crow.sg/apps/ai-agent-remote/docs/troubleshooting.md)- Everything in one file: https://crow.sg/apps/ai-agent-remote/docs/llms-full.txt