# AI Agent Remote > Install the open-source bridge, pair your phone and watch or control the coding agents running in terminals on your own computer. Source: https://crow.sg/apps/ai-agent-remote/docs/ Watch and steer the coding agents running in terminals on your own computer from your phone. A small open-source bridge runs next to your terminals and the app talks straight to it: no account, no hosted service, nothing uploaded to us. ## Get started in a few minutes Install the bridge on the Mac or Linux computer where your agents run: ```sh title="macOS or Linux · install script" curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | sh ``` ```sh title="Homebrew" brew tap crow-tech-pte-ltd/agent-remote-bridge https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge brew install agent-remote-bridge ``` Both put `agent-remote` on your path. The script installs to `~/.local/bin` without sudo, checks the download against the release’s SHA-256 checksums and, if `~/.local/bin` isn’t on your `PATH` yet, adds it to your shell’s startup file (`~/.zshrc` on a Mac); open a new terminal window afterwards. Set `AGENT_REMOTE_NO_MODIFY_PATH=1` to leave your shell files alone. The script is published on crow.sg from `install.sh` in the [bridge repository](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge), and downloads the kits from its GitHub Releases. To read it before running it: `curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | less` ```sh agent-remote up ``` Then open AI Agent Remote on a phone on the same Wi-Fi. Your computer appears under **On this network**; tap it, and type the 6-digit code that pops up on the computer. That’s it. The [quickstart](https://crow.sg/apps/ai-agent-remote/docs/quickstart/) walks through each step, including computers without Herdr. - **iPhone & iPad:** Coming soon to the App Store - **Android:** Coming soon - **Bridge for macOS & Linux:** [Free and open source · GitHub](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/releases/latest) ## How it fits together Phone (AI Agent Remote) → TLS pinned to your computer → bridge (`agent-remote` on your Mac or Linux computer) → same user account → your terminals (Herdr, Orca or plain shells running Claude Code, Codex, …). The phone talks to the bridge on your computer over TLS pinned to that computer’s own certificate, directly on your network or through a relay you run. The bridge drives the terminals as you; your agents and model accounts stay where they are. The bridge is the `agent-remote` program. It reads your terminal workspaces from **Herdr** (a terminal workspace manager for coding agents), **Orca**, or from plain shells it runs itself, and serves them to the phones you pair. Your coding agents keep running on the computer with your own accounts; the phone only shows and types into what is already there. ## What you can do - **See who needs you.** Agents waiting for input, finished or working, across every project. - **Take the terminal.** A live terminal with special keys, sized to your screen while you control it. - **Read the conversation.** Agent history paged back to the start of the session, with search. - **Speak a prompt.** Voice notes transcribed on your phone, edited before you send. - **Review the changes.** Branch, changed files and diffs for each project. - **From anywhere.** On your Wi-Fi, through your VPN, or through a relay you run. ![Attention screen listing an agent that needs input and one that finished](https://crow.sg/apps/ai-agent-remote/docs/app-attention.webp "Attention") ![An agent conversation with earlier messages and tool calls](https://crow.sg/apps/ai-agent-remote/docs/app-history.webp "Agent history") ![Changes view with branch, ahead and behind counts and changed files](https://crow.sg/apps/ai-agent-remote/docs/app-changes.webp "Changes") ## What you need - A Mac (Apple silicon or Intel) or a Linux computer (x86-64 or ARM64) that stays awake while you use the phone. - Optionally Herdr or Orca. Without them, `--backend plain` lets the bridge run its own shells. - An iPhone or iPad on iOS 17 or later. The app is in testing and coming soon to the App Store; Android is coming soon. - Your coding agents (Claude Code, Codex, OpenCode, Gemini CLI and [others](https://crow.sg/apps/ai-agent-remote/docs/backends/#agents)) installed and signed in on the computer, as you use them today. ## Next steps - [Quickstart](https://crow.sg/apps/ai-agent-remote/docs/quickstart/): From download to your first terminal in a few minutes. - [Set up with an AI agent](https://crow.sg/apps/ai-agent-remote/docs/ai-setup/): A ready-to-paste prompt that lets a coding agent install and pair the bridge with you. - [Install the bridge](https://crow.sg/apps/ai-agent-remote/docs/install/): macOS and Linux kits, running it as a service, updating. - [Pair a phone](https://crow.sg/apps/ai-agent-remote/docs/pairing/): Nearby code or QR invitation, read or control. - [Using the app](https://crow.sg/apps/ai-agent-remote/docs/using-the-app/): Attention, projects, terminals, keys, history, voice and changes. - [Web console](https://crow.sg/apps/ai-agent-remote/docs/console/): Agents, devices, pairing and settings in your browser. - [Web remote](https://crow.sg/apps/ai-agent-remote/docs/web-remote/): The app in a browser, on this computer or your network. - [Reach it from anywhere](https://crow.sg/apps/ai-agent-remote/docs/remote-access/): Your VPN, the reverse relay and the home network. - [Backends & agents](https://crow.sg/apps/ai-agent-remote/docs/backends/): Herdr, Orca or plain terminals, and the agents recognised. - [Security](https://crow.sg/apps/ai-agent-remote/docs/security/): What protects a connection, and how it compares with SSH. - [CLI reference](https://crow.sg/apps/ai-agent-remote/docs/cli/): Every agent-remote command and flag. - [Troubleshooting](https://crow.sg/apps/ai-agent-remote/docs/troubleshooting/): Fixes for the common problems, and answers to questions. --- # Quickstart > Install the AI Agent Remote bridge, start it with agent-remote up and pair your phone with a 6-digit code. Source: https://crow.sg/apps/ai-agent-remote/docs/quickstart/ This gets a phone on your Wi-Fi watching the terminals on your computer. It takes about five minutes. To reach the computer from elsewhere afterwards, see [Reach it from anywhere](https://crow.sg/apps/ai-agent-remote/docs/remote-access/). ## Four steps 1. **Install the bridge on your computer** ```sh title="macOS or Linux · install script" curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | sh ``` ```sh title="Homebrew" brew tap crow-tech-pte-ltd/agent-remote-bridge https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge brew install agent-remote-bridge ``` Both put `agent-remote` on your path. The script installs to `~/.local/bin` without sudo, checks the download against the release’s SHA-256 checksums and, if `~/.local/bin` isn’t on your `PATH` yet, adds it to your shell’s startup file (`~/.zshrc` on a Mac); open a new terminal window afterwards. Set `AGENT_REMOTE_NO_MODIFY_PATH=1` to leave your shell files alone. The script is published on crow.sg from `install.sh` in the [bridge repository](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge), and downloads the kits from its GitHub Releases. To read it before running it: `curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | less` Or [download a release kit](https://crow.sg/apps/ai-agent-remote/docs/install/#kit) by hand. 2. **Start it** ```sh agent-remote up ``` On first run, `up` creates the bridge’s private state in `~/.local/share/herdr-remote`: a TLS certificate for this computer’s `.local` name and network addresses, and a small database of paired phones. It then listens on port 8443, advertises the computer to phones on the same network, and opens the [web console](https://crow.sg/apps/ai-agent-remote/docs/console/) in your browser. ```sh title="First start" output Created bridge state in /Users/you/.local/share/herdr-remote address https://studio.local:8443 (also 192.168.1.20) pin 81d45cb9b691e5d8a3254dbac95ce7fb3fc170d266cf53d0d906117e62b54e6c {"event":"listening","url":"https://studio.local:8443","discoverable":true,…} Console: http://127.0.0.1:8790/#launch=… ``` > [!NOTE] No Herdr? > Run `agent-remote up --backend plain`. The bridge then runs its own login shells, one in your home folder to start with, and you add project folders from the phone. Agents you start in them are recognised. The choice is remembered, so later a plain `up` is enough. With Herdr, run the bridge in a Herdr tab so it finds the `herdr` command, or pass `--herdr "$(which herdr)"`. macOS may ask to allow incoming connections or devices on your local network: allow both. On Linux, install `avahi-utils` so phones can find the computer, and allow TCP port 8443 from your network if a firewall is on. 3. **Install the app** - **iPhone & iPad:** Coming soon to the App Store - **Android:** Coming soon - **Bridge for macOS & Linux:** [Free and open source · GitHub](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/releases/latest) Before you pair, **Explore preview** in the app shows clearly labelled sample projects, so you can look around without a computer. 4. **Pair with the code on your computer** Open the app and allow Local Network access. Your computer appears under **On this network**. Tap **Pair**: a 6-digit code pops up on the computer (as a notification, in Herdr, and in the terminal running `up`). Type it on the phone and check that the fingerprint matches on both screens. ```sh title="On the computer" output Pairing request: Example iPhone Code 482 913 · fingerprint b636-f910 Type this code on the phone. It expires in 2 minutes. ``` ![On this network section listing two computers with Pair buttons](https://crow.sg/apps/ai-agent-remote/docs/app-nearby.webp "Your computer, found on the network") ![Pair computer sheet asking for the 6-digit code and showing the fingerprint to compare](https://crow.sg/apps/ai-agent-remote/docs/app-pair-code.webp "Type the code, compare the fingerprint") ![Attention screen after pairing](https://crow.sg/apps/ai-agent-remote/docs/app-attention.webp "Paired: your agents appear") Done. The phone saves the computer and reconnects by itself from now on. Open **Projects**, pick a pane, and you are watching it live. ## Where next - Keep the bridge running after you close the terminal: [run it as a service](https://crow.sg/apps/ai-agent-remote/docs/install/#service). - Pair on a network you don’t trust, or pair read-only: [use a QR invitation](https://crow.sg/apps/ai-agent-remote/docs/pairing/#qr). - Learn the terminal controls, history, voice notes and changes in [Using the app](https://crow.sg/apps/ai-agent-remote/docs/using-the-app/). - Leave the house: [reach the computer from anywhere](https://crow.sg/apps/ai-agent-remote/docs/remote-access/). --- # Set up with an AI agent > Copy a ready-made prompt that lets an AI coding agent such as Claude Code or Codex install the AI Agent Remote bridge, pair your phone and keep it running. Source: https://crow.sg/apps/ai-agent-remote/docs/ai-setup/ If you already use a coding agent in a terminal, let it do the setup with you. **Copy for my AI**, at the top of every docs page, copies the prompt below. Paste it into Claude Code, Codex, Gemini CLI or another agent running on the computer where your agents run. ## What the agent does - Asks a few questions first: your operating system, Herdr, Orca or plain shells, read or control access, and whether you need to reach the computer away from home. - Installs the bridge, starts it and checks that it is listening. - Stops for you when the phone is involved: you type the 6-digit code, compare fingerprints, or scan a QR invitation yourself. - Optionally installs the bridge as a service and sets up remote access through your VPN or a relay you run. - Checks each step, and knows the common pitfalls from [Troubleshooting](https://crow.sg/apps/ai-agent-remote/docs/troubleshooting/). > [!WARNING] Keep invitations to yourself > Pairing invitations, QR codes, console links and relay profiles work like passwords. The prompt tells the agent not to print them into the chat; run `agent-remote pair` yourself, in a terminal only you can see. ## The prompt ````markdown 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 ```` The agent can read any page of these docs as Markdown: add `.md` to a page's address (the overview is [index.md](https://crow.sg/apps/ai-agent-remote/docs/index.md)), or fetch [llms-full.txt](https://crow.sg/apps/ai-agent-remote/docs/llms-full.txt) for everything in one file. --- # Install the bridge > Install the open-source AI Agent Remote bridge on macOS or Linux, keep it running as a service and update it. Source: https://crow.sg/apps/ai-agent-remote/docs/install/ The bridge is a single program, `agent-remote`, that runs as you on the computer where your terminals are. It is free and open source under Apache-2.0; its source, protocol and releases are on [GitHub](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge). Its earlier name, `herdr-remote`, still works and runs the same program. ## Requirements | | Needed | | --- | --- | | 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 ```sh title="macOS or Linux · install script" curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | sh ``` ```sh title="Homebrew" brew tap crow-tech-pte-ltd/agent-remote-bridge https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge brew install agent-remote-bridge ``` Both put `agent-remote` on your path. The script installs to `~/.local/bin` without sudo, checks the download against the release’s SHA-256 checksums and, if `~/.local/bin` isn’t on your `PATH` yet, adds it to your shell’s startup file (`~/.zshrc` on a Mac); open a new terminal window afterwards. Set `AGENT_REMOTE_NO_MODIFY_PATH=1` to leave your shell files alone. The script is published on crow.sg from `install.sh` in the [bridge repository](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge), and downloads the kits from its GitHub Releases. To read it before running it: `curl -fsSL https://crow.sg/apps/ai-agent-remote/install.sh | less` ### Download a release kit Every bridge release on [GitHub Releases](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/releases/latest) has a ready-to-run kit for each computer. Each zip unpacks to an `agent-remote` folder holding the `agent-remote` program (a single file, no runtime to install), a README and the licences. The release lists SHA-256 checksums in `SHA256SUMS`. | Computer | Download | | --- | --- | | Mac with Apple silicon (M1 and later) | `agent-remote-bridge-VERSION-macos-arm64.zip` | | Intel Mac | `agent-remote-bridge-VERSION-macos-x64.zip` | | Linux x86-64 | `agent-remote-bridge-VERSION-linux-x64.zip` | | Linux ARM64 | `agent-remote-bridge-VERSION-linux-arm64.zip` | ```sh title="macOS" cd ~ unzip ~/Downloads/agent-remote-bridge-*-macos-*.zip # creates ~/agent-remote cd ~/agent-remote xattr -dr com.apple.quarantine . # macOS blocks downloaded programs otherwise ./agent-remote up ``` ```sh title="Linux" cd ~ unzip ~/Downloads/agent-remote-bridge-*-linux-*.zip # creates ~/agent-remote cd ~/agent-remote ./agent-remote up ``` ### Container image A multi-architecture image is published at `ghcr.io/crow-tech-pte-ltd/agent-remote-bridge`. It suits a relay server, or a bridge that runs plain terminals inside the container. A bridge that should drive Herdr or Orca on your own desktop belongs on that computer instead. ```sh title="Docker" docker pull ghcr.io/crow-tech-pte-ltd/agent-remote-bridge:latest ``` If you keep the kit in `~/agent-remote`, run it as `./agent-remote` from that folder, or add the folder to your `PATH`. The rest of these docs write plain `agent-remote`. ## First start ```sh agent-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. | Option | Effect | | --- | --- | | `--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? `agent-remote init` then `agent-remote serve` gives you full control over the address, listener and certificate names; see the [CLI reference](https://crow.sg/apps/ai-agent-remote/docs/cli/). ## Keep it running The bridge serves phones only while it runs. To start it with the computer from now on, run this once (with the same options you give `up`, for example `--backend plain`): ```sh agent-remote service install agent-remote service status # installed, running, starts at boot or at login agent-remote service uninstall # stop it and remove it ``` - On Linux it is a systemd user service named `agent-remote`. It starts when you log in; to start it at boot without logging in, run `loginctl enable-linger "$USER"` once. Its log: `journalctl --user -u agent-remote -f`. - On macOS it is a LaunchAgent named `sg.crowtech.agent-remote` that starts when you log in. It logs to `service.log` in the state folder. macOS doesn't let background services use Downloads, Desktop or Documents, so keep an unzipped kit somewhere else, such as `~/Applications/agent-remote`. - The service runs the bridge with your terminal's PATH, so it finds Herdr and your agents, and it keeps working after the bridge updates itself. Run `service install` again to change its options. - It replaces a `herdr-remote` service set up from an earlier template. If a bridge is already running in a terminal, stop it first. > [!NOTE] > A bridge started by a service never opens a browser. Run `agent-remote console` for a one-time console link. Keep the Mac from sleeping (System Settings → Battery or Energy) if you want to reach it away from the desk. ## Update Bridges from 0.1.30 on update themselves: they check GitHub Releases, verify the new kit against its checksums and restart once no phone has been connected for two minutes. `agent-remote update --check` shows what is available, `agent-remote update` installs it now, and `agent-remote update --mode notify` (or `off`) only tells you. The iPhone app shows the same notice with an Update now button. Older bridges: run the install script again, run `brew upgrade agent-remote-bridge` or replace the kit folder, then start the bridge 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 ```sh agent-remote service uninstall # if you started it with the computer rm -rf ~/agent-remote # the program, if you unzipped a kit rm -rf ~/.local/share/agent-remote-bridge # or, from the install script rm -f ~/.local/bin/agent-remote ~/.local/bin/herdr-remote rm -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](https://bun.sh) 1.3.9 or later and OpenSSL installed: ```sh git clone https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge.git cd agent-remote-bridge/server bun install --frozen-lockfile bun src/cli.ts up ``` `bun build src/cli.ts --compile --outfile agent-remote` makes the same single-file program the kits contain. --- # Pair a phone > Pair AI Agent Remote with your computer using a nearby 6-digit code or a QR invitation, choose read or control access, and revoke devices. Source: https://crow.sg/apps/ai-agent-remote/docs/pairing/ Pairing gives one phone its own credential for one computer, and teaches the phone that computer’s exact certificate. There are two ways to do it, and two levels of access. ## Nearby: type a code When the bridge was started with `agent-remote up` (or `serve --discoverable`), phones on the same network list it under **On this network**. Tap **Pair**, and a 6-digit code appears on the computer: as a desktop notification, as a Herdr notification and in the terminal running the bridge. Type it on the phone. ![Computers found on this network, each with a Pair button](https://crow.sg/apps/ai-agent-remote/docs/app-nearby.webp "Computers on this network") ![Code entry with the fingerprint the computer also shows](https://crow.sg/apps/ai-agent-remote/docs/app-pair-code.webp "Enter the code and compare the fingerprint") - A code expires after two minutes or five wrong tries. - Both screens show the first eight characters of the certificate fingerprint. If they differ, cancel: something else answered on your network. - Phones paired this way get the access set in the console under **Access for phones paired with a code** (control by default). > [!WARNING] Nearby pairing trusts your network for the first contact > Someone able to impersonate your computer on the same network during that minute could stand in the middle; the fingerprint check is how you notice. On a café, hotel or office network, use a QR invitation instead, and turn advertising off with `--no-discovery`. ## QR invitation Run this on the computer, in a terminal only you can see: ```sh agent-remote pair --scope control --qr ``` In the app choose **Connect a computer** (or **+** → **Pair a computer**), scan the QR code, check the address and connection method it shows, name the device and pair. The QR code carries the computer’s address, its full certificate fingerprint and a one-time code, plus the relay route if the bridge has joined one. | Option | Effect | | --- | --- | | `--scope read\|control` | Access for the new device. The default is read. | | `--ttl 300` | Seconds the invitation stays valid, 1 to 3600. The default is five minutes. | | `--qr` | Draw the QR code in the terminal as well as printing the link. | | `--json` | Print the invitation as JSON, to paste into the app instead of scanning. | | `--no-relay` | Leave the relay route out, for a direct-only invitation. | | `--url ADDRESS` | Put another address in this invitation, such as a VPN address, if the bridge certificate covers it. The saved address stays. | The [web console](https://crow.sg/apps/ai-agent-remote/docs/console/) can show the same QR code with a read or control choice and a lifetime. No camera handy, or the code is on the phone itself? **Choose photo or screenshot** on the pairing screen reads the QR code from a picture in your library. It needs no photo permission: the app only sees the picture you pick. Invitations from bridge 0.1.37 and later also carry the computer’s local network addresses. If the saved address stops answering, for example a `.local` name over a VPN, the app tries those and uses the one that answers, always checking the same certificate. > [!WARNING] An invitation is a secret > Anyone who scans it before it expires can pair. It works once; don’t paste it into chat, screenshots or support requests. Make a new one if it expired or was used. ## Read or control | | Read | Control | | --- | --- | --- | | Watch panes and agents live | Yes | Yes | | Agent history, files, Git changes | Yes | Yes | | Type, send prompts and voice notes | No | Yes, while it holds control of that pane | | Create workspaces and tabs, start agents, close panes | No | Yes | A control device is as powerful as a shell on your computer as your user. Give control only to your own devices; a read device suits a tablet on the desk or a teammate looking over your shoulder. ### Taking control of a pane Typing into a pane needs a short control lease for that pane, tied to the program running in it. Opening a terminal takes it automatically if your device has control access (turn off **Fit terminals to this screen** to only watch). Only one device controls a pane at a time, and the device you are using wins: opening a pane, or coming back to the app with one open, takes control from another device, which then watches with a notice. Reconnecting never takes control from another device. Leaving the pane, or the app staying in the background for about 20 seconds, releases control, and keystrokes are never replayed after a dropped connection. ![Observing label with a Take control button](https://crow.sg/apps/ai-agent-remote/docs/app-observing.webp) ## List and revoke devices ```sh agent-remote devices agent-remote revoke --device 0821ea58-c654-4dce-9346-01206ea81d9e ``` ```sh title="agent-remote devices" output [ { "id": "0821ea58-c654-4dce-9346-01206ea81d9e", "name": "Example iPhone", "scope": "control", "createdAt": 1793433255523, "revokedAt": null } ] ``` Revoking cuts the device off at once, including live sessions and any control it holds. A relay started with `--personal-only` refuses it too. The console has a Revoke button per device. On the phone, **Forget** in Connections removes the saved credential locally; it does not revoke it on the computer, so revoke lost phones from the computer. --- # Using the app > Attention, projects, pane labels, the live terminal and its special keys, the message box, voice notes, agent history and search, Git changes, the iPad layout and connections in AI Agent Remote. Source: https://crow.sg/apps/ai-agent-remote/docs/using-the-app/ The app has three tabs: **Attention** for what needs you, **Projects** for everything on the computer, and **Connections** for your paired computers. It follows your phone’s light or dark appearance and text size. Screenshots here use the app’s built-in preview projects. ## Attention Attention gathers the agents that **need input**, the ones that **finished**, and the panes you opened **recently**, across all your projects. The row of counters at the top filters by state: needs input, working, done, idle and plain terminals. With two or more kinds of agent, a second row filters by agent. Tap a row to open that pane. Each row shows the agent’s logo, its name (or the pane’s label), the workspace and folder, its state and how long ago it last wrote. The **View** menu switches between **Detailed** rows and denser **Compact** ones. ![Attention with a Claude Code agent needing input and a Codex agent finished, each with its logo](https://crow.sg/apps/ai-agent-remote/docs/app-attention.webp "Needs input and finished") ![Attention in dark appearance](https://crow.sg/apps/ai-agent-remote/docs/app-attention-dark.webp "Dark appearance") ## Projects Projects lists every workspace, its tabs and panes, with each agent’s state. Collapse the workspaces you aren’t following. With control access you can also create a **New workspace** or **New tab**, **Split right** or **Split below**, **Start an agent** from the agents installed on the computer, and **Close pane** (which ends the program in it). A new workspace, tab or split asks for a folder: type its full path, such as `/Users/you/projects/new-idea`. If the folder doesn’t exist yet, the computer creates it, with any missing parent folders, and opens the terminal there (bridge 0.1.41 or later; older bridges need an existing folder). With Orca, **Import repository** adds an existing Git repository instead. **Add label…** on a row or in a pane’s menu names the pane, for example after the task it’s on. With Herdr the label is Herdr’s own pane label, so you see it on the computer too (bridge 0.1.29 or later). ![Projects grouped by workspace and tab, with labels, logos and agent states](https://crow.sg/apps/ai-agent-remote/docs/app-projects.webp "Workspaces, tabs and panes") ![A pane's terminal, watching](https://crow.sg/apps/ai-agent-remote/docs/app-terminal.webp "A pane’s terminal") Each pane has three views, switched from the menu under its title: **Activity** (recent output or the agent conversation), **Terminal** (the live screen) and **Changes** (Git). ## The live terminal The Terminal view streams the pane’s real screen as it changes. If your device has control access, opening it takes control and fits the terminal to your phone: the computer’s pane is resized to the phone’s width so nothing scrolls sideways, and its size is restored when you leave. Turn off **Fit terminals to this screen** to watch at the computer’s size instead, zooming with a pinch. - **Text size.** While you control a fitted pane, the floating A− and A+ buttons, or a pinch, set the terminal text size from 7 to 24 points. Smaller text gives you more columns and rows. - **Scrollback.** Drag to scroll the pane’s own history; **Latest** or typing returns to the bottom. - **Programs that restart.** When an agent exits and starts again in the same pane, the app follows the pane to its new program and never sends it input meant for the old one. - **Pane actions.** The ⋯ menu has Interrupt (Ctrl C), End input (Ctrl D), Suspend (Ctrl Z), Clear screen (Ctrl L), Release control and Take over. ## Message box or terminal keyboard **Type with** chooses how you type. The **Message box** (default) is a normal text field at the bottom: write or dictate a whole prompt, edit it with the usual iOS tools, and send it in one go. The text is pasted into the pane and followed by Enter, the way agents expect a prompt. **Terminal keyboard** sends each keystroke straight to the terminal, for shells, editors and menus. With a hardware keyboard (an iPad’s, for example), **Return sends** the message, Shift-Return adds a line and Command-Return always sends. On the on-screen keyboard, Return adds a line and the arrow button sends. Turn off **Hardware keyboard: Return sends** in the pane menu to make a keyboard’s Return add lines too. The message box doesn’t capitalise your first letter, so commands stay as you type them. ### Special keys A compact key dock sits above the keyboard (hide it with **Show special keys**). Swipe it sideways for three pages; the page name flashes as you switch. | Page | Keys | | --- | --- | | Keys | Shift, Ctrl, Alt, Esc, Tab, Enter, the arrows and Ctrl C | | Scroll | Page Up, Page Down, Home, End, Ctrl Home, Ctrl End, Shift Page Up/Down, Backspace, Delete, Ctrl L | | Ctrl | Ctrl D, Z, R, O, T, B, A, E, U, W and K | ![Keys page: Shift, Ctrl, Alt, Esc, Tab, Enter, arrows, Ctrl C and the message box](https://crow.sg/apps/ai-agent-remote/docs/app-keys.webp "Keys") ![Scroll page: Page Up, Page Down, Home, End and more](https://crow.sg/apps/ai-agent-remote/docs/app-keys-scroll.webp "Scroll") ![Ctrl page with common control keys](https://crow.sg/apps/ai-agent-remote/docs/app-keys-ctrl.webp "Ctrl") ## Voice notes Tap the microphone in the message box, or **Voice note** in the prompt draft, and speak. A timer and level meter show it is recording; the bin discards it. Stop, and the recording is transcribed **on your phone** and added to your draft, unsent, for you to review and edit. Choose the **Speech language** next to the button. The recording is deleted once it is transcribed. ![Recording a voice note with a timer and level meter](https://crow.sg/apps/ai-agent-remote/docs/app-voice-recording.webp "Recording") ![Prompt draft with the transcribed text added](https://crow.sg/apps/ai-agent-remote/docs/app-voice-draft.webp "Transcribed into the draft") > [!NOTE] > Transcription never falls back to a cloud service: if your phone or language has no on-device speech support, pick another language or type. Nothing is sent until you press send with control of the pane. ## History and search Tap the history button on a terminal to read back. For agents whose session the bridge can find (**Claude Code**, **Codex**, **Pi** and **Qwen Code**), history is the agent’s own conversation: your prompts, its replies and folded tool calls (the wrench shows or hides tool detail). **Earlier messages** at the top pages back to the start of the session. Replies keep their formatting: headings, emphasis, lists, code and tables (fitted to the screen). For other programs it is the terminal’s output: up to 1,000 lines with Herdr, and 500, 1,000 or 2,000 lines with plain terminals and Orca. - **Find** (the magnifier, or Command-F on a keyboard) searches the loaded history. - Select and copy any text; whole lines stay intact when they wrap. - A− and A+ (or a pinch) change the history text size. - The link button turns web links in replies into links you can tap; they open in your browser. - **Live** returns to the terminal. ![Conversation history with Earlier messages at the top](https://crow.sg/apps/ai-agent-remote/docs/app-history.webp "Conversation with earlier messages") ![Conversation history with tool calls expanded](https://crow.sg/apps/ai-agent-remote/docs/app-history-tools.webp "Tool calls shown") ![Find in history with a highlighted match](https://crow.sg/apps/ai-agent-remote/docs/app-history-find.webp "Find in history") ## Files and Git changes **Changes** shows the project’s branch, how far it is ahead of or behind its upstream, and each changed file with lines added and removed. Tap a file for its diff, or browse the project’s files. Large or binary files may not preview, and ignored or sensitive paths can be hidden. ![Changes with branch, ahead/behind and two changed files](https://crow.sg/apps/ai-agent-remote/docs/app-changes.webp "Changed files") ![A unified diff of one file](https://crow.sg/apps/ai-agent-remote/docs/app-diff.webp "A file’s diff") ## On iPad On iPad the sidebar, the list and the open pane share the screen, so you can move between agents while a terminal or conversation stays open. A hardware keyboard types into the terminal or the message box, and Command-F finds in history. ![AI Agent Remote on iPad: the sidebar, the Attention list and an agent's conversation side by side](https://crow.sg/apps/ai-agent-remote/docs/ipad-history.webp) ## Connections and leaving the app **Connections** lists your paired computers. Switch between them, or swipe one and choose **Forget** to remove it from this phone (revoke it on the computer too; see [Pairing](https://crow.sg/apps/ai-agent-remote/docs/pairing/#devices)). - **Change address…** points the app at a new address for a computer, for example after it moved to another network. The app saves it only after the computer at that address proves it is the same one. - **Updates**: when a newer bridge is out, Attention says so and, with control access, **Update now** installs it. The app also tells you about a new version of itself. **Show update notices** under Updates turns both off. - **Connection log** shows the app’s recent connection events, to copy into a bug report. It stays on the phone. Switching to another app for a moment keeps everything connected for about 20 seconds. After that the app releases control and closes its connections; when you come back it reconnects and opens where you were. It also reconnects by itself when the network changes, keeping the last screen meanwhile. iOS does not keep connections open in the background indefinitely, so live viewing happens with the app open. Want to try the interface first? **Explore preview** on the Attention tab opens clearly labelled sample projects without any computer. The Atlas API project in these screenshots comes from that preview. --- # Web console > The AI Agent Remote bridge's local web console: every agent and what it is doing, devices, recent activity, pairing, network, web remote, certificate, updates and settings in your browser. Source: https://crow.sg/apps/ai-agent-remote/docs/console/ The bridge serves a dashboard to your own browser: every agent and what it is doing, paired devices and when each last connected, what happened recently, pairing, how phones reach this computer, the web remote, the certificate, updates and settings. The CLI and the console edit the same `config.json`. ## Open it `agent-remote up` and `serve` start the console at `http://127.0.0.1:8790` (or the next free port) and, in a desktop terminal, open it in your browser already signed in. A bridge started as a service or over SSH doesn’t open a browser; ask it for a link instead: ```sh agent-remote console ``` The link works once and for two minutes, then the browser keeps a session for twelve hours. To turn the console off, start with `--no-console` or set `"console": false` in the config (Settings has the same switch). The dashboard below is bridge 0.1.39 and later; it updates itself every few seconds. ![Bridge console overview: agents waiting for input with their logos, paired devices, recent activity and how phones reach the computer](https://crow.sg/apps/ai-agent-remote/docs/console-overview-light.webp "Overview of a bridge with three paired devices. The agents in the list are examples.") ## What’s in it The sidebar has a page for each part of the bridge. | Page | What it does | | --- | --- | | Overview | A Get set up checklist on a new bridge. Agents that need input or have finished, each with Open to go straight to it in the web remote. Counts of agents and terminals, paired devices and how many are connected now, recent activity, how phones reach this computer, and days left on the certificate. | | Agents | Every agent and terminal, grouped by workspace, with its logo, label, folder, state and when it last wrote. Filter by state, search by name or folder, and Open any of them in the web remote. | | Devices | Every paired phone and browser with its access, whether it is connected now and when it last connected. Rename or revoke one; filter phones or browsers, and show revoked ones. | | Pair a phone | A QR code for watch-only or control access, valid from 5 minutes to an hour, and whether phones nearby can pair with a 6-digit code (turned on under Network). | | Network | The address new invitations carry (change it, as with agent-remote address set), where the bridge listens for phones, nearby discovery and its access, and the relay: join one by pasting its profile, see whether it is connected, or leave it. | | Web remote | Open the app in this browser, and turn on the web remote for other devices on your network (HTTPS on port 8791, with a password). | | Certificate | Fingerprint and expiry; renew early. Paired phones move to the new certificate by themselves. | | Updates | The installed and newest bridge version, Update now, and whether the bridge installs updates itself, only tells phones, or never checks. | | Settings | The name phones see, whether the bridge starts with the computer (and the command that sets that up), the terminal backend (Herdr program and session, Orca, or plain folders), and the console’s own switch and port. Settings that need it apply with a restart in place; a banner offers it. | ## Agents **Agents** lists everything running in your terminals, by workspace: the agent’s logo with a dot for its state, the pane’s label if you gave it one, its folder and when it last wrote. The sidebar counts the agents that need input. The console shows names and places only, never terminal or conversation text; Open shows the pane in the [web remote](https://crow.sg/apps/ai-agent-remote/docs/web-remote/). ![The console's Agents page: api, web and docs workspaces with Claude Code, Codex, Gemini CLI, OpenCode and terminals, filters and a search box](https://crow.sg/apps/ai-agent-remote/docs/console-agents-light.webp "Agents, filtered by state or found by name or folder") ## Getting set up On a new bridge the Overview starts with three steps, ticked off as they happen: pair a phone, start the bridge with the computer, and reach it away from home (through a relay, or tell it you use your own VPN). **Hide** puts the checklist away. ![Get set up: Pair your first phone done, Start the bridge with this computer and Reach it away from home still to do](https://crow.sg/apps/ai-agent-remote/docs/console-setup-light.webp) ![Start with this computer: Not set up, with the agent-remote service install command and a copy button](https://crow.sg/apps/ai-agent-remote/docs/console-service-light.webp "Settings: whether the bridge starts with the computer") ![Address phones use: https://studio.local:18843 with a field to change it](https://crow.sg/apps/ai-agent-remote/docs/console-address-light.webp "Network: the address new invitations carry") **Start with this computer** reads the same status as `agent-remote service status`. Installing the service is a command you run in a terminal (see [Keep it running](https://crow.sg/apps/ai-agent-remote/docs/install/#service)); the console doesn’t install it for you. ## Recent activity The Overview lists what happened lately: phones and browsers paired, signed in or revoked, a device connecting after a while away, the relay connecting or dropping, the bridge starting, updating or restarting, a new certificate, and settings you changed. Pairings and revocations are kept in the bridge’s state; the rest lasts until the bridge process stops. ![Recent activity: the bridge started, three phones paired and an old phone revoked](https://crow.sg/apps/ai-agent-remote/docs/console-activity-light.webp) ## Light, dark and narrow screens The console follows your system’s light or dark appearance. In a narrow window the sidebar becomes a menu. ![The console's Agents page in dark appearance](https://crow.sg/apps/ai-agent-remote/docs/console-agents-dark.webp "Dark appearance") ![Bridge console at phone width with its menu open](https://crow.sg/apps/ai-agent-remote/docs/console-phone-menu.webp "Phone width, menu open") ## Who can open it - It listens on 127.0.0.1 only: other machines, your phone and the relay can’t reach it. The [web remote](https://crow.sg/apps/ai-agent-remote/docs/cli/#web) on your network is separate and never reaches the console’s settings. - A browser gets in only through a one-time link that only your user account can create, then holds an HttpOnly, SameSite=Strict session cookie. - Every change checks the Host and Origin headers and a CSRF token, so other web pages can’t drive it. Responses never contain device tokens, relay secrets or private keys, and the page loads nothing from the internet. > [!NOTE] Using it from another computer > Forward the port over SSH, then ask the bridge for a link: > > ```sh > ssh -L 8790:127.0.0.1:8790 you@your-computer > agent-remote console # on that computer; open the link locally > ``` > [!WARNING] Don’t screenshot a pairing QR code > The QR code the console shows is a one-time secret. Anyone who scans it before it expires can pair a device. --- # Web remote > Use AI Agent Remote in a browser: agents, the live terminal with take control, history, files and Git changes, served by the bridge on your computer or, with a password, on your network. Source: https://crow.sg/apps/ai-agent-remote/docs/web-remote/ The web remote is the app in a browser, served by the bridge itself. It shows the same agents, terminals, history and changes as your phone, and uses the same protections: each browser is a paired device with read or control access, and typing needs control of the pane. ## Open it On the computer running the bridge, choose **Open web remote** in the [console](https://crow.sg/apps/ai-agent-remote/docs/console/), or ask for a one-time link: ```sh agent-remote web ``` On this computer the browser signs in through the console, without a password. Nothing is loaded from the internet: the page, its terminal (xterm.js) and the agents’ logos come from the bridge. ![The web remote: agents and terminals by workspace on the left; on the right a terminal in control showing git output, with special keys and a message box](https://crow.sg/apps/ai-agent-remote/docs/remote-terminal-light.webp "A terminal in control. The agents in the list are examples.") ## What you can do | Part | What it does | | --- | --- | | Attention and Projects | Agents that need input or finished, recent panes, and every workspace, tab and pane. Each agent shows its maker’s logo and its pane label if it has one; filter by state. | | Terminal | The pane’s live screen. Take control to type: straight into the terminal, with the special keys (Esc, Tab, Ctrl C, arrows, Page Up and more), or in the message box, which sends a whole prompt followed by Enter (Enter sends and Shift-Enter adds a line; on a phone, Enter adds a line). Fit to window resizes the pane to the browser while you control it. | | History | The agent’s conversation for Claude Code, Codex, Pi and Qwen Code, with earlier messages, tool calls and find; terminal output for other programs. | | Changes and Files | The branch, changed files and each file’s diff, and the project’s files. | A pane opens watching; **Take control** lets you type. One device controls a pane at a time: if a phone holds it, **Take over** asks first. Leaving the tab hidden for 20 seconds releases control, and a read-only browser can only watch. ![The web remote's Changes tab listing changed files](https://crow.sg/apps/ai-agent-remote/docs/remote-changes-light.webp "Changes") ![A file's diff in the web remote, dark appearance](https://crow.sg/apps/ai-agent-remote/docs/remote-diff-dark.webp "A diff, in dark appearance") ## On your network To use it from another computer or a tablet on your network, set a password, then turn on **Serve the web remote on the network** under **Web remote** in the console. It applies at once. ```sh agent-remote web password ``` It is served over HTTPS with the bridge’s own certificate on port 8791 (change it in the console, or with `"webPort"` in the config), at the addresses the console lists. Choose whether browsers signed in there can control panes or only read. > [!WARNING] Check the fingerprint before typing the password > The browser warns the first time because the bridge made its own certificate. Open the certificate from the address bar and compare its SHA-256 fingerprint with the one in the console’s Web remote section. If they differ, don’t sign in. Wrong passwords are slowed down, and 20 failures turn network sign-in off until the bridge restarts. The console’s settings, pairing and devices are never served on the network. ## Browsers are devices Each browser that signs in is listed under **Devices** in the console and in `agent-remote devices`, as “Web browser” with its browser and where it signed in. Revoke it there to sign it out at once; signing out in the browser does the same. See [Security](https://crow.sg/apps/ai-agent-remote/docs/security/) for how sessions are protected. --- # Reach it from anywhere > Reach your computer from AI Agent Remote away from home: through your own VPN, a reverse relay you run with no inbound port, or app-only WireGuard. Source: https://crow.sg/apps/ai-agent-remote/docs/remote-access/ On your Wi-Fi, the phone talks straight to the computer. Away from it, pick one of three routes. Each keeps the same end-to-end TLS pinned to your computer, the same device credentials and the same control rules. ## Choose a route | Route | Good when | You need | | --- | --- | --- | | Your own VPN | You already use Tailscale, WireGuard or similar on the phone | The bridge listening on its VPN address | | Reverse relay | The computer is behind NAT or a work firewall, or you don’t want a VPN on the phone | A small server with HTTPS that you run; no inbound port on the computer | | App-only WireGuard | You run a WireGuard server and want only this app to use it | A WireGuard peer for each phone | The phone never falls back from one route to another on its own, and a relay or VPN can’t read or type into your terminals. See [Security](https://crow.sg/apps/ai-agent-remote/docs/security/) for why. ## Your own VPN If your phone and computer share a VPN, give the bridge the computer’s VPN address. For a new bridge, initialise it with that address before the first start: ```sh agent-remote init --url https://100.101.102.103:8443 --listen 0.0.0.0 --port 8443 agent-remote serve agent-remote pair --scope control --qr ``` The address in `--url` is the one the phone dials and is always included in the certificate; add others with `--san`. An IP address is the tested form on iPhone. `init` never overwrites existing state. For a bridge that already exists: - If your VPN reaches your home network, there may be nothing to do: invitations carry the computer’s local addresses, and when the saved address (often a `.local` name, which VPNs don’t resolve) doesn’t answer, the app tries those. - `agent-remote address` shows the saved address and every name the certificate covers; `agent-remote address set ADDRESS` (or Network in the console) changes what new invitations carry, and `pair --url ADDRESS` makes one invitation for another covered address. Paired phones keep their pairing; in the app, **Change address…** under Connections points a phone at the new address. - For an address the certificate doesn’t cover, use a separate `--state` directory with `init` and pair again. ## Reverse relay The bridge dials _out_ to a relay you run, over ordinary HTTPS on port 443, and phones reach the relay from anywhere. Nothing listens on the computer’s network, so it works from behind NAT, a work firewall or a proxy (the bridge honours `HTTPS_PROXY`). ```text output title="How the relay connects" phone ──WSS──▶ relay you run ◀──WSS (dials out)── bridge on your computer │ (HTTPS, port 443) ▲ └──────── TLS pinned to your computer's own certificate ─┘ ``` The relay joins two outgoing connections and copies bytes between them. Inside, the phone runs TLS that ends at your computer and accepts only its certificate, so the relay sees encrypted traffic, never your terminals. > [!NOTE] > One relay serves one bridge. The iPhone and iPad app supports relays; the Android app does not yet. Per-device relay credentials need bridge 0.1.25 or later. 1. **Run the relay on a server** Any small Linux server with a public name works. The relay is the same `agent-remote` program: ```sh agent-remote relay serve --listen 127.0.0.1 --port 8788 ``` ```sh output {"event":"relay_listening","port":8788} ``` Put HTTPS in front of it with your reverse proxy or Cloudflare Tunnel, forwarding only `/v1/tunnel` and `/v1/host` and keeping WebSocket upgrades. For example, with Caddy: ```Caddyfile title="Caddyfile" relay.example.com { reverse_proxy /v1/tunnel 127.0.0.1:8788 reverse_proxy /v1/host 127.0.0.1:8788 } ``` The relay keeps its own secrets in `~/.local/share/herdr-remote-relay`. Run it as a service the same way as the bridge. 2. **Make a relay profile** ```sh agent-remote relay profile --public-url wss://relay.example.com > relay.json chmod 600 relay.json ``` ```sh title="relay.json (secrets shown as )" output { "version": 1, "host": { "url": "wss://relay.example.com/v1/host", "token": "" }, "phone": { "mode": "gateway", "gateway": { "url": "wss://relay.example.com/v1/tunnel", "token": "" } } } ``` The profile holds two separate random secrets: one the bridge uses to register, one phones use to get in. Copy it to your computer privately (for example with `scp`) and keep it mode 600. 3. **Join the relay from your computer** ```sh agent-remote relay join relay.json ``` ```sh output {"joined":true,"relay":"relay.example.com","next":"restart serve/up, then pair --scope control --qr"} ``` Restart the bridge. It now keeps one outgoing connection to the relay and reconnects with backoff if it drops: ```sh agent-remote up ``` ```sh output {"event":"listening","url":"https://studio.local:8443","relay":true,"localRoute":true,…} {"event":"relay_connected","url":"relay.example.com"} ``` 4. **Pair through the relay** ```sh agent-remote pair --scope control --qr ``` The invitation now carries the relay route and a relay credential made for that one phone. Scan it, and the phone reaches your computer from any network. Phones paired before you joined need a fresh QR invitation to learn the route. ### Home network, automatically A bridge that has joined a relay still answers phones on its own network, and tells paired phones its local addresses. At home the phone connects directly; when you leave, it switches back to the relay. Nothing needs re-pairing, and the phone checks the same certificate either way. To keep the bridge on loopback only, start it with `--no-local-route` or untick the option in the console. ### Keeping the relay tight - Each phone gets its own relay credential, and the bridge tells the relay which ones to admit every few seconds. Once all your phones have connected with a current app, restart the relay with `--personal-only` so the shared phone secret no longer works and revoked phones are refused at the relay. Keep the shared secret while you use the Android app. - `agent-remote relay rotate --public-url wss://relay.example.com` issues new relay secrets; join again with the new profile. - The console shows relay connections admitted and rejected, and warns if another connection took over with the bridge’s credential. - `agent-remote relay status` and `relay leave` show or remove the profile, and `pair --no-relay` makes a direct-only invitation. ## App-only WireGuard The iPhone and iPad app has WireGuard built in for its own connection only: it doesn’t install a VPN profile or touch other apps’ traffic. If you run a WireGuard server that can reach the computer, you can pair in either of two ways: - Create the invitation with a private route file: `agent-remote pair --scope control --qr --connection wireguard-route.json`. The format is described in [connection-routes.md](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge/blob/main/protocol/connection-routes.md). - Or, while pairing, choose **Connection options → Paste WireGuard configuration** and import a standard single-peer config. The app narrows it to the one computer you are pairing with. Give each phone its own peer: two devices sharing one peer key interrupt each other. A guided container setup that bundles a WireGuard endpoint with the bridge is being prepared for the public repository. ## Keep the computer reachable Whatever the route, the computer must be on, awake and running the bridge. Run the bridge [as a service](https://crow.sg/apps/ai-agent-remote/docs/install/#service), and stop the computer from sleeping while you want to reach it. --- # Backends & agents > Use AI Agent Remote with Herdr, Orca or plain terminals, and the coding agents the bridge recognises. Source: https://crow.sg/apps/ai-agent-remote/docs/backends/ The bridge serves one kind of terminal at a time, its _backend_: Herdr, Orca, or plain shells it runs itself. Choose with `--backend herdr|orca|plain`; the choice is saved, and the console can change it. ## Herdr (default) Herdr is a terminal workspace manager for coding agents. With this backend, Herdr owns the workspaces, tabs, panes and agent sessions; the bridge shows them to your phone and passes your input through. Watching uses a read-only helper, so it never takes over the desktop’s view. ```sh agent-remote up # finds herdr on the PATH agent-remote up --herdr "$(which herdr)" # or say where it is agent-remote serve --session work # pick a Herdr session (default: the main one) ``` The easiest setup is to run the bridge in a Herdr tab. Pairing codes also appear as Herdr notifications. Terminal history reaches back up to Herdr’s 1,000 most recent lines; agent conversations go further (see below). ## Orca The bridge can attach to a local Orca runtime instead. Orca’s own runtime access link stays in a private file on the computer; the phone pairs with the bridge’s usual invitation. Use a separate state directory and port if you also run a Herdr bridge. ```sh agent-remote init --backend orca --orca-connection ~/private/orca-access.txt \ --url https://192.168.1.20:8444 --listen 0.0.0.0 --port 8444 --state ~/.local/share/herdr-remote-orca agent-remote serve --state ~/.local/share/herdr-remote-orca ``` - Orca’s desktop and its own clients can still type into the same terminal; control leases coordinate only the phones paired with the bridge. - **Import repository** registers an existing local Git repository. Starting an agent inside an existing pane is not available; start it from Orca or by typing the command. ## Plain terminals No Herdr or Orca? The bridge runs its own login shells, as you: ```sh agent-remote up --backend plain agent-remote up --backend plain --folder ~/code/api --folder ~/code/web ``` - Each folder becomes a workspace with one shell (your home folder if you give none). Add more from the phone with **New workspace**, in a new folder too (the bridge creates it); they are remembered for the next start. - The terminals themselves end when the bridge stops. - One device controls a terminal at a time, and the terminal’s size follows it. History keeps 500, 1,000 or 2,000 lines. - Agents you start in these shells are recognised and shown as agents. ## Agents The bridge recognises an agent from the program running in a pane, and offers the ones installed on the computer under **Start an agent**. For agents marked below, the app reads the agent’s own session log to show its conversation, paged back to the start; for the others it shows the terminal output and says why. | Agent | Command | Conversation history | | --- | --- | --- | | Claude Code | `claude` | Yes | | Codex | `codex` | Yes | | OpenCode | `opencode` | Terminal output | | Pi | `pi` | Yes | | Gemini CLI | `gemini` | Terminal output | | Qwen Code | `qwen` | Yes | | Kimi Code | `kimi` | Terminal output | | GitHub Copilot CLI | `copilot` | Terminal output | | Cursor CLI | `cursor-agent` | Terminal output | | Droid | `droid` | Terminal output | | Amp | `amp` | Terminal output | | Kiro CLI | `kiro-cli` | Terminal output | | Cline | `cline` | Terminal output | | Kilo Code | `kilo` | Terminal output | | Qoder CLI | `qodercli` | Terminal output | | Devin CLI | `devin` | Terminal output | | Antigravity CLI | `agy` | Terminal output | | Grok CLI | `grok` | Terminal output | | Hermes Agent | `hermes` | Terminal output | | Oh My Pi | `omp` | Terminal output | | Mastra Code | `mastracode` | Terminal output | | Letta Code | `letta` | Terminal output | | Maki | `maki` | Terminal output | | Muse | `muse` | Terminal output | | Crush | `crush` | Terminal output | | Goose | `goose` | Terminal output | | Aider | `aider` | Terminal output | | Auggie | `auggie` | Terminal output | | CodeBuddy | `codebuddy` | Terminal output | | ZCode (Z.ai) | `zcode` | Terminal output | | DeepSeek Harness | `dsh` | Terminal output | > [!NOTE] > Agents keep running on your computer with your own accounts, settings and model providers; any usage charges are between you and them. The app doesn’t sign in to anything and never approves an agent’s request on its own: a waiting agent shows as **Needs input** until you answer it. --- # Security > How AI Agent Remote protects the connection between your phone and your computer, what a relay can and cannot see, and how it compares with SSH. Source: https://crow.sg/apps/ai-agent-remote/docs/security/ A paired phone with control access can do what you can do at your keyboard, so the bridge is built to let in only the phones you pair, and to keep everything in between unable to read or change what flows. This page summarises our own review; it is not an independent audit. ## What protects a connection - **End-to-end TLS pinned to your computer.** The bridge makes its own certificate. The phone learns its exact SHA-256 fingerprint from the QR code you scan (or checks it against the computer during nearby pairing) and accepts no other: no certificate authority, no “trust anyway”. Current apps require TLS 1.3. - **A credential per device.** Pairing gives each phone a random 256-bit token; the bridge stores only its hash. Each device is read-only or may control terminals, and revoking it cuts it off at once, live sessions included. - **Explicit control.** Typing needs a control lease for that pane, checked against the program currently running in it. Keystrokes are never replayed after a dropped connection, and a command whose delivery is uncertain is never resent automatically. - **Relays carry ciphertext only.** Through a relay, the phone’s TLS still ends at your computer. Each phone has its own relay credential, and relayed connections are never treated as your local network. - **Certificate renewal keeps pairings.** Thirty days before the certificate expires, the bridge makes a successor and signs its fingerprint with the current key. Phones that connect before the switch verify that and move over; others pair again. - **Private state.** The certificate key, configuration and device database live in a folder only your user can read. Logs record lifecycle events, not tokens, invitations, prompts or file contents. - **A local-only console.** The web console listens on 127.0.0.1, admits a browser only through a one-time link your account creates, and checks Host, Origin and a CSRF token on every change. ## Who can see what | If this is compromised… | …it can | …it cannot | | --- | --- | --- | | Your Wi-Fi, VPN or a relay (and any proxy or CDN in front of it) | See when you connect and how much data flows; drop or slow connections | Read terminals, files or prompts, or type anything: it has no device token and fails the certificate pin | | The relay’s phone secret | Knock on the bridge’s front door: health checks and pairing, which still needs a fresh one-time code | Use the phone API without a paired device | | The relay’s bridge secret | Pretend to be your computer to the relay, knocking the real one off | Fool phones: they reject anything without your computer’s certificate | | A phone or its device token | Whatever that device’s access allows; with control, the same as a shell as you | Outlast a revoke: revoke lost phones from the computer | | Your user account on the computer | Everything, as with SSH | Nothing extra: the bridge runs as you | ## Compared with SSH **Encryption and server authentication are comparable.** SSH and TLS both use modern authenticated encryption with forward secrecy. On first contact, pinning is arguably stricter than typical SSH use: SSH asks you to accept an unknown host key, which most people do without checking, while the phone gets the exact fingerprint from a QR code you scan in person. ### Where SSH is ahead - **Client keys.** SSH keys never leave the device and can live in hardware. Our device token is a bearer secret sent, inside the pinned TLS, with each request. Hardware-bound device keys are planned. - **Maturity.** OpenSSH has decades of scrutiny. The bridge is new code and has not been independently audited. ### Where this is ahead - **Scope.** Read-only devices exist; an SSH login is usually all or nothing. - **Explicit control.** Typing needs a lease tied to the pane’s program and is never replayed. - **Revocation.** One command or click per device, which also ends its live sessions. - **No open port.** With the relay, the computer accepts no inbound connection, and the relay refuses anyone without a credential before our protocol is reachable. For confidentiality and integrity, the relay path is about as strong as SSH, because it rests on standard TLS with an exact certificate pin, not on the relay. ## Known limits - Device tokens are bearer secrets; device-bound keys are planned. - Bridges still accept TLS 1.2 from older app versions. - A relay accepts its shared phone secret until you start it with `--personal-only` (older pairings and the Android app use it). - Nearby pairing trusts the local network for the first contact; compare the fingerprint, or pair by QR code on networks you don’t trust. - A reverse proxy on the same computer makes remote connections look local; leave nearby discovery off in that setup. ## Good practice - Pair only your own devices, and give control only where you need it. - Keep phones locked, and revoke a lost phone from the computer straight away. - Treat pairing QR codes, invitations and relay profiles as secrets. - Try workspace creation, splits and closing panes in a throwaway project first. - Keep the bridge updated. > [!NOTE] Report a problem > Please report security problems privately to [hello@crow.sg](mailto:hello@crow.sg) rather than in a public issue. The bridge’s source is on [GitHub](https://github.com/Crow-Tech-Pte-Ltd/agent-remote-bridge). --- # CLI reference > Every agent-remote command and option: up, service, init, serve, pair, devices, revoke, address, console, web, update, certificate and the relay commands. Source: https://crow.sg/apps/ai-agent-remote/docs/cli/ The bridge is one program, `agent-remote` (`herdr-remote`, its earlier name, still works). Every command accepts `--state DIR` (default `~/.local/share/herdr-remote`), `--json` and `--help`. ## Output and help In a terminal, commands answer in readable, coloured text: aligned fields, a table of devices, the pairing code in a box. Piped or redirected output, and any command with `--json`, is JSON (the bare link for `pair`, `console` and `web`), so scripts and services read the same thing every time. Colour follows `NO_COLOR`, `FORCE_COLOR` and `TERM=dumb`; bridge 0.1.38 and later. ```sh agent-remote help # every command, grouped agent-remote help pair # one command's options (same as: agent-remote pair --help) agent-remote devices --json # for scripts ``` ![agent-remote --help in a dark terminal: commands grouped under Start, Phones, In a browser, Upkeep and From anywhere](https://crow.sg/apps/ai-agent-remote/docs/cli-help.webp "agent-remote --help") ![agent-remote up in a dark terminal: the bridge set up, ready with its addresses, and a pairing code in a box](https://crow.sg/apps/ai-agent-remote/docs/cli-up.webp "agent-remote up, then a phone asking to pair") ## Commands at a glance | Command | What it does | | --- | --- | | [up](https://crow.sg/apps/ai-agent-remote/docs/cli/#up) | First-run setup plus serve, advertised on your Wi-Fi with code pairing. | | [init](https://crow.sg/apps/ai-agent-remote/docs/cli/#init) | Create state with an explicit address, listener and certificate names. | | [serve](https://crow.sg/apps/ai-agent-remote/docs/cli/#serve) | Run the bridge from existing state. | | [pair](https://crow.sg/apps/ai-agent-remote/docs/cli/#pair) | Make a one-time pairing invitation, optionally as a QR code. | | [devices](https://crow.sg/apps/ai-agent-remote/docs/cli/#devices) | List paired devices. | | [revoke](https://crow.sg/apps/ai-agent-remote/docs/cli/#revoke) | Unpair a device at once. | | [address](https://crow.sg/apps/ai-agent-remote/docs/cli/#address) | Show or change the address invitations give phones. | | [console](https://crow.sg/apps/ai-agent-remote/docs/cli/#console) | Print a one-time link to the local web console. | | [web](https://crow.sg/apps/ai-agent-remote/docs/cli/#web) | Print a one-time link to the web remote, or set its network password. | | [update](https://crow.sg/apps/ai-agent-remote/docs/cli/#update) | Install the newest release now, or choose how updates happen. | | [service install \| status \| uninstall](https://crow.sg/apps/ai-agent-remote/docs/cli/#service) | Start the bridge with the computer (systemd user service or LaunchAgent). | | [certificate](https://crow.sg/apps/ai-agent-remote/docs/cli/#certificate) | Show the certificate, or renew it early. | | [relay join \| status \| leave](https://crow.sg/apps/ai-agent-remote/docs/cli/#relay) | Connect this bridge to a relay, or stop. | | [relay serve \| profile \| rotate](https://crow.sg/apps/ai-agent-remote/docs/cli/#relay-serve) | Run a relay, make its profile, replace its secrets. | | `help [COMMAND]` | List the commands, or show one command’s options. | ## agent-remote up ```sh title="Usage" agent-remote up [--port 8443] [--name NAME] [--no-discovery] [--backend herdr|orca|plain] ``` The one-step command for a computer on your Wi-Fi. On first run it creates TLS material for this computer’s `.local` name and private addresses, listening on all interfaces; then it serves, advertises the computer to phones nearby, and opens the console. Pairing needs the code that pops up on this computer. | Option | Meaning | | --- | --- | | `--port 8443` | Port for phones, used when creating state. | | `--name NAME` | Name shown on the phone. | | `--no-discovery` | Don’t advertise this computer or accept nearby code pairing. | | `--backend herdr\|orca\|plain` | Which terminals to serve; saved for next time. | | `--folder DIR` | Plain backend: open this folder as a workspace (repeatable). | | `--herdr PATH` | Path to the herdr program. | | `--no-console` | Don’t start the local web console. | | `--no-local-route` | With a relay: don’t also accept phones on this network. | ## agent-remote init ```sh title="Usage" agent-remote init --url https://host.example:8443 [--listen 127.0.0.1] [--port 8443] [--san localhost,127.0.0.1] ``` Creates the private state directory with a one-year self-signed certificate. It never overwrites an existing certificate or paired devices. | Option | Meaning | | --- | --- | | `--url URL` | The HTTPS address phones dial. Its host is always in the certificate. | | `--listen ADDRESS` | Interface to listen on: 127.0.0.1 for this computer only, 0.0.0.0 for the network. | | `--port PORT` | Listening port. | | `--san NAMES` | Extra comma-separated names or addresses for the certificate. | | `--name, --backend, --herdr, --session, --orca-connection` | As for up and serve. | ## agent-remote serve ```sh title="Usage" agent-remote serve [--backend herdr|orca|plain] [--herdr /path/to/herdr] [--session NAME] [--discoverable] ``` Runs the bridge from existing state, keeping a relay connection open if it has joined one. Command-line options win over the saved config for this run; settings saved in the console replace them. The bridge checks its certificate every few hours and renews it 30 days before expiry. | Option | Meaning | | --- | --- | | `--backend herdr\|orca\|plain` | Terminal backend for this run. | | `--herdr PATH` | Path to the herdr program. | | `--session NAME` | Herdr session to serve (default: the main one). | | `--orca-connection FILE` | Orca: private file with the local runtime link. | | `--folder DIR` | Plain backend: a folder to open as a workspace (repeatable). | | `--discoverable` | Advertise on the network and accept nearby code pairing. | | `--listen, --port` | Override the saved listener for this run. | | `--no-console` | Don’t start the web console. | | `--no-local-route` | With a relay: stay on loopback, relay only. | ## agent-remote pair ```sh title="Usage" agent-remote pair [--scope read|control] [--ttl 300] [--uses 1] [--qr] [--url ADDRESS] [--json] [--connection PRIVATE_PROFILE.json] [--no-relay] ``` Prints a `herdr-remote://pair?data=…` link containing a short-lived, single-use secret. Show it only to the device’s owner. It works while the bridge runs. The invitation also lists this computer’s network addresses, so a phone that can’t resolve its name (away on a VPN, for example) reaches it by IP. | Option | Meaning | | --- | --- | | `--scope read\|control` | Access for the new device. Default: read. | | `--ttl SECONDS` | How long the invitation is valid, up to 2592000 (30 days). Default: 300. | | `--uses N` | How many phones can pair with it, up to 20. Default: 1. | | `--qr` | Also draw a QR code in the terminal. | | `--url ADDRESS` | This invitation only: another address the certificate covers, such as an IP address. | | `--json` | Print the invitation as JSON for pasting into the app. | | `--connection FILE` | Add a private route (secure gateway or app-only WireGuard). | | `--no-relay` | Leave out the relay route. | ## agent-remote devices ```sh title="Usage" agent-remote devices [--all] ``` Lists paired devices with their name, access, when they were paired and their ID. | Option | Meaning | | --- | --- | | `--all` | Also list revoked devices. | ## agent-remote revoke ```sh title="Usage" agent-remote revoke --device ID ``` Revokes a device at once, closing its sockets and releasing any control it holds. The first 8 characters of the ID, as `devices` shows it, are enough when no other device starts with them. ## agent-remote address ```sh title="Usage" agent-remote address agent-remote address set ADDRESS ``` Shows the address new invitations give phones, the other addresses they list, and the names the certificate covers. `set` changes it: a name or IP address, optionally with a port, or a URL (`192.168.1.20`, `studio.local:8443`, `https://studio.local:8443`). The certificate must cover it. Paired phones keep their pairing and learn this computer’s addresses when they connect; nothing is re-paired or revoked. Bridge 0.1.37 and later. ## agent-remote console ```sh title="Usage" agent-remote console ``` Prints a one-time link (valid two minutes) to the running bridge’s local web console. `up` and `serve` open it themselves in a desktop terminal; turn it off with `--no-console` or `"console": false`. See [Web console](https://crow.sg/apps/ai-agent-remote/docs/console/). ## agent-remote web ```sh title="Usage" agent-remote web agent-remote web password [--clear] ``` `web` prints a one-time link that opens the app in a browser on this computer. `web password` sets the password for using it from other devices on your network (typed twice, or read from standard input); then turn it on in the console or with `"webLan": true`. It is served over HTTPS with the bridge certificate on port 8791. ## agent-remote update ```sh title="Usage" agent-remote update [--check] [--mode auto|notify|off] ``` Installs the newest release the same way this copy was installed (install script, Homebrew or an unzipped kit, never with sudo), checks it against the release’s checksums and restarts the running bridge into it. Bridges before 0.1.30 can’t update themselves: install once by hand. | Option | Meaning | | --- | --- | | `--check` | Only report whether a newer release exists. | | `--mode auto` | Default. The bridge installs new releases itself and restarts once no phone has been connected for two minutes. | | `--mode notify` | Only tell paired phones that an update is available. | | `--mode off` | Never check. | ## agent-remote service ```sh title="Usage" agent-remote service install|status|uninstall [--state DIR] [serve options] ``` On Linux this is a systemd user service (`~/.config/systemd/user/agent-remote.service`), on macOS a LaunchAgent (`~/Library/LaunchAgents/sg.crowtech.agent-remote.plist`, logging to `service.log` in the state folder). It takes the serve options such as `--backend`, `--folder`, `--discoverable` and `--no-console`, and your terminal's PATH. Without bridge state it creates it first, as `up` does. It replaces an older `herdr-remote` service and refuses while a bridge started in a terminal uses the same state folder. Needs bridge 0.1.34 or later. | Option | Meaning | | --- | --- | | `install` | Write, enable and start a service named agent-remote that runs agent-remote serve with these options. Run it again to change them. | | `status` | Whether it is installed and running, and on Linux whether it starts at boot or at login. | | `uninstall` | Stop it and remove the file install wrote. | ## agent-remote certificate ```sh title="Usage" agent-remote certificate [renew [--days N]] ``` Without arguments, shows the current fingerprint and expiry. Paired phones pick up a renewed certificate automatically. ```sh output Fingerprint c794 4b5a a4a8 75bf 7b22 264d ce1d 701f eee5 0aba d524 83bf 24e3 2aed 9265 c3a1 Expires 31 Oct 2027 (in 12 months) ``` With `--json`: `{"pin":"c7944b5a…","expiresAt":"2027-10-31T07:53:31.000Z"}`. | Option | Meaning | | --- | --- | | `renew --days N` | Create a successor now and switch to it after N days (default 14, at the latest a day before expiry). | ## agent-remote relay ```sh title="Usage" agent-remote relay join PRIVATE_RELAY.json agent-remote relay status agent-remote relay leave ``` `join` saves a relay profile privately in the state directory; restart `serve` or `up` to connect, and new invitations carry the relay route. `status` shows the joined relay, `leave` removes it. See [Reverse relay](https://crow.sg/apps/ai-agent-remote/docs/remote-access/#relay). ## agent-remote relay serve ```sh title="Usage" agent-remote relay serve [--listen 127.0.0.1] [--port 8788] [--state DIR] [--personal-only] agent-remote relay profile --public-url wss://relay.example.com > PRIVATE_RELAY.json agent-remote relay rotate --public-url wss://relay.example.com ``` Run on the relay server. `profile` prints the private profile the bridge joins with; `rotate` issues new relay secrets, after which bridges join again. | Option | Meaning | | --- | --- | | `--listen, --port` | Where the relay listens; put HTTPS/WSS in front of it. | | `--state DIR` | Relay secrets folder. Default: ~/.local/share/herdr-remote-relay. | | `--personal-only` | Admit only the per-device credentials the bridge lists; revoked phones are refused. | | `--public-url URL` | The relay’s public root wss:// address, written into the profile. | ## Files | Path | Contents | | --- | --- | | `~/.local/share/herdr-remote/config.json` | Settings, certificate and its private key (mode 600). | | `~/.local/share/herdr-remote/` | Device database, relay profile (relay.json), plain-terminal folders. | | `~/.local/share/herdr-remote-relay/` | A relay server’s secrets. | --- # Troubleshooting > Fixes for common AI Agent Remote problems: discovery, pairing, relays, certificates, control, history and voice notes, plus frequently asked questions. Source: https://crow.sg/apps/ai-agent-remote/docs/troubleshooting/ Most problems come down to the phone not reaching the bridge, or the bridge not finding your terminals. Start with what the bridge prints, or its status in the [console](https://crow.sg/apps/ai-agent-remote/docs/console/). ## Finding and pairing ### My computer doesn’t appear under “On this network” - Check the phone and computer are on the same Wi-Fi, and not a guest network that isolates devices. - On the iPhone, allow Local Network for AI Agent Remote in Settings → Privacy & Security → Local Network. - Start the bridge with `agent-remote up` (or `serve --discoverable`), not with `--no-discovery`. - On Linux, install `avahi-utils` and make sure the avahi daemon is running. - Still nothing? Pair with a QR code instead: `agent-remote pair --scope control --qr`. ### No code popped up on the computer The code appears in the terminal running the bridge, as a desktop notification and in Herdr. If you missed it, tap **Show a new code** on the phone. Codes expire after two minutes or five wrong tries. ### The fingerprints don’t match Cancel. Something other than your computer answered. Pair with a QR code shown on the computer itself, ideally on another network. ### The QR invitation says it expired or was used Invitations are single-use and last five minutes by default. Run `agent-remote pair` again, or use `--ttl` for longer (up to 30 days). ### macOS won’t open agent-remote Remove the download quarantine from the kit folder once: ```sh xattr -dr com.apple.quarantine ~/agent-remote ``` ## The bridge ### “A bridge already owns this state directory” Another bridge is running with the same state, perhaps as a service. Stop it first, or run a second bridge with its own `--state` directory and port. ### It can’t find Herdr Run the bridge in a Herdr tab, or tell it where Herdr is with `--herdr "$(which herdr)"`. Services have a shorter PATH than your shell. No Herdr at all? Use `--backend plain`. ### The port is already in use Choose another with `--port` when the state is first created, or change **Phone API port** in the console. Paired phones are told about the change. ### Where are the logs? The bridge logs to the terminal it runs in. As a Linux service: `journalctl --user -u herdr-remote -f`. Logs contain events, not tokens, prompts or file contents. ## Away from home and relays ### It works at home but not anywhere else The home address (`yourcomputer.local` or a 192.168… address) can’t be reached from elsewhere. Set up [a VPN, a relay or app-only WireGuard](https://crow.sg/apps/ai-agent-remote/docs/remote-access/), then pair again so the phone learns the route. ### The bridge never prints relay_connected - Check `agent-remote relay status` and that you restarted the bridge after joining. - Your HTTPS proxy must forward `/v1/host` and `/v1/tunnel` with WebSocket upgrades. - Behind a corporate proxy, set `HTTPS_PROXY`; if it inspects TLS, put its root certificate in `NODE_EXTRA_CA_CERTS`. - If the relay was rotated, join again with the new profile. ### The relay refuses my phone A relay started with `--personal-only` admits only per-device credentials. Phones paired before bridge 0.1.25, and the Android app, still use the shared secret: pair them again, or run the relay without `--personal-only` for now. ### The certificate changed or expired Renewed certificates are picked up automatically by phones that connect before the switch. Otherwise, pair again with a fresh invitation. Never try to turn off certificate checks. ## In the app ### I can watch but not type The device may be paired read-only (pair again with `--scope control`), or another device controls the pane: choose **Take over** from the ⋯ menu. ### A command shows delivery as unknown The connection dropped while sending. Look at the terminal before sending again: the app never resends uncertain input by itself, because the agent may already have received it. ### History shows terminal output, not the conversation Conversation history is available for Claude Code, Codex, Pi and Qwen Code when the bridge can find the agent’s session. The app says why when it falls back. Herdr keeps at most 1,000 lines of terminal history. ### Voice notes aren’t available Transcription happens only on the phone. If your device doesn’t support on-device speech for the chosen language, choose another language or type; check that the app has microphone and speech recognition access in Settings. ### It disconnects when I switch apps iOS doesn’t keep connections open in the background. The app holds on for about 20 seconds, then releases control; when you return, it reconnects and opens where you were. ## Questions ### Does it cost anything? No. The app has no subscription or in-app purchase, and the bridge is free and open source. Your coding agents and model providers bill you as they do today. ### Does Crow Tech see my code or terminals? No. The phone talks to your computer directly or through a relay you run, encrypted end to end to your computer. There is no Crow account, and the app has no analytics. See the [privacy policy](https://crow.sg/apps/ai-agent-remote/privacy/). ### Windows? The bridge runs on macOS and Linux. Windows is not supported yet. ### Is this an official Herdr or Orca app? No. AI Agent Remote is an independent companion project by Crow Tech. ### Something else is wrong See [Help & support](https://crow.sg/apps/ai-agent-remote/support/) or email [hello@crow.sg](mailto:hello@crow.sg?subject=AI%20Agent%20Remote%20support) with the app and bridge versions, your device, and what happened. Leave out tokens, QR codes, invitations, relay profiles and private code.