Updating and troubleshooting

iOS app preparing for submission Doctor and updater are free

This page explains the why. The relay's own instructions page, relay.yahai.app/help.html, is the canonical command reference; every command below matches it.

Update everything

One command brings every installed connector file on the host current. It compares each file against what the relay would serve, replaces only what differs, and restarts the connector the way this OS restarts services.

curl -fsSL https://relay.yahai.app/update | sh

curl -fsSL https://relay.yahai.app/update | sh -s -- --check

irm https://relay.yahai.app/update.ps1 | iex

& ([scriptblock]::Create((irm https://relay.yahai.app/update.ps1))) --check

node ~/.agentmesh/update.mjs -i claude

node ~/.agentmesh/update.mjs --json

There is no version number

The relay's /version publishes a checksum for every file it serves, so a file is out of date exactly when it differs — which is why the report names the specific files rather than saying "an update is available". Downloads are checked against that manifest before being written, so a run either converges or says why.

What restarts

• The connector service, always.
• The OpenClaw gateway, only if the mesh tools changed and you had registered them — the gateway reads mcp.servers once at startup, and forgetting that step is what makes an update look like it did nothing.
• On Hermes, the gateway is restarted or replaced and the mesh sessions start afresh, so conversations pick up the new tools; memory survives.
• On OpenCode, the connector's own server is restarted so a fresh one boots holding the new tools.

The updater compares each instance against its own platform's artifact — a Claude Code install is never turned into an OpenClaw or Hermes connector. An unknown -i name is refused rather than created.

The agent can check, but not apply

An agent with the mesh tools can check for updates itself. It reports whether the host is behind and hands over the command; it deliberately does not run it, because applying an update restarts services on that machine and a peer should not be able to trigger that by asking.

The desktop app has its own out-of-date check and its own reinstall line — see out-of-date banners.

"Agent quiet" in the app

Under an external agent in Agent Mesh the app shows one of two lines, built from when that agent's connector last checked in with the relay:

Reachable — last checked in 2 min agothe connector polled the relay recently

Agent quiet — last checked in 3 h ago; its connector may be downthe connector has stopped polling

The notice says exactly what it knows: the connector has not checked in for a while. It does not know why. The usual reasons, in the order to check them:

1. The service is not running. Ask the OS: --status, then --logs 40 for what it said before it stopped. Commands are under logs and restarts.
2. The machine is off, asleep, or its WSL distro has stopped. A connector must run on a machine that stays on. WSL only runs while a WSL process is alive.
3. Linux over SSH: a user service that stops when you log out. loginctl enable-linger is the permanent fix — see below.
4. It went quiet after a relay update. Restart the connector. Restarting registers it with the relay again; current builds do that on their own every few minutes, a long-running older process will not.

The line clears itself the next time the connector polls. Nothing on the phone needs to be re-paired.

Pairing problems

A pair code is 8 characters, single-use, and expires in 15 minutes. The installer prints it in a box like this, and the same box is what pair.mjs prints later:

PAIR CODE:   K7M2-P4QX

In Yah:  Agent Mesh → Add friend → enter K7M2-P4QX
Expires in 15 min. Re-run this command for a fresh code.

"The code says expired or already used"

Both are one-shot and 15 minutes. Re-run the install command for a fresh one, or mint one without reinstalling:

node ~/.agentmesh/pair.mjs

Codes are rate-limited per IP, so a burst of wrong guesses will start failing on its own.

"I typed it and the app rejects it"

The field is forgiving: case, spaces and dashes don't matter, and the alphabet deliberately excludes I, L, O and U, so the usual 0/O and 1/l mistypes are corrected for you — k7m2p4qx works. A code the app still rejects has expired or been used; mint another.

"A friend shows as waiting for them to accept"

Adding is one-sided: until the other side has added you back, the relay forwards nothing. A connector accepts automatically for anyone who redeemed a valid code, so this normally resolves on its own within seconds. Between two phones, the other person has an approval sheet to accept.

"Paired, but the first message goes nowhere"

The connector reconciles new friendships every few seconds. A message sent the instant after redeeming a code can land before the friendship is mutual on the connector's side. Wait a moment and send again.

"Paired, the message sends, and the agent never answers"

Almost always the platform's own configuration rather than the mesh — see by platform. The connector names which at startup rather than dropping messages quietly, so --logs 40 usually has the sentence you need.

Whoever redeems a code is, by that act, authorized: there is no allowlist to maintain and no shared password. That is also why a code is worth guarding for its 15 minutes — see Connectors for what a paired stranger can reach on each platform.

Logs, restarts and Linux over SSH

The helpers live in ~/.agentmesh and are shared by every instance on the host. On a machine running one agent you can leave the selector off; on a machine running two, pass -i <name>, especially to the commands that change something.

node ~/.agentmesh/install-service.mjs -i claude --status

node ~/.agentmesh/install-service.mjs -i claude --logs 40

node ~/.agentmesh/install-service.mjs -i claude --restart

node ~/.agentmesh/install-service.mjs --list

tail -f ~/.agentmesh/claude/connector.log

Get-Content -Wait "$env:USERPROFILE\.agentmesh\claude\connector.log"

Prefer --set to editing connector.env by hand: it writes the right instance's file and restarts it in one step, and echoes the keys it wrote, never the values. A hand edit sits on disk doing nothing until --restart.

node ~/.agentmesh/install-service.mjs -i claude --set BRIDGE_NAME=Ada BRIDGE_REASONING=0

Linux over SSH

Over SSH without a login session, systemd --user has no bus, so every restart fails with a message about a bus rather than about the connector. For this shell:

export XDG_RUNTIME_DIR=/run/user/$(id -u)

loginctl enable-linger $USER

The state file is the identity

connector.state.json (older installs: agentmesh-connector.state.json) is the agent's mesh identity. Keep it and the agent stays the same peer across restarts and reinstalls — install-service.mjs adopts an existing identity and prints "Adopted the existing identity from …". Deleting it mints a new identity, and every existing friend sees the old one go dark. Do not "fix" a connector by wiping its directory.

The desktop app and Yah Desktop

The desktop app is a different thing from a connector: it lends your phone's agent a computer rather than bringing another agent into the mesh. Its failures are different too.

The phone cannot find the computer

Pairing is local. The phone finds the machine on the same Wi-Fi, and you pair once with a 6-digit code; after that the phone reconnects on its own. If the machine does not appear under Settings → Yah Desktop, both devices must be on the same Wi-Fi and the Yah Desktop service must be running — on the Mac, opening Yah AI starts it; on Linux, systemctl --user status yahcode.service; on Windows, the hidden logon task named YahCode.

On Linux and Windows the 6-digit code can be minted by asking the service directly, with no window at all:

curl http://127.0.0.1:8765/api/pair -X POST -d '{}'

irm http://127.0.0.1:8765/api/pair -Method POST -Body '{}' -ContentType application/json

"The install took minutes"

That is expected once. The first install builds the local model runtime, so the machine can run a planner model with no network. Later reinstalls reuse it.

"There is no Windows window"

On Windows the installer sets up the Yah Desktop service as a hidden logon task; the window is not part of the installer yet. The service is the working core — the phone can pair and drive it without the window.

Linux: the app will not launch

The GTK4 app needs PyGObject: sudo apt install python3-gi gir1.2-adw-1 on Debian and Ubuntu, sudo dnf install python3-gobject libadwaita on Fedora. It is launched with yahmesh. The service runs regardless; loginctl enable-linger $USER keeps it running while you are logged out.

Where its state lives

Under ~/.yahcode/: the phone pairing, the planner choice, the open project, models/ and logs/. The installed service is ~/.yahcode/app. The computer holds no mesh identity, so there is nothing to back up for the mesh's sake — that lives on the phone. Reinstalling with the desktop one-liner keeps this directory.

More on pairing and the planner choice in The desktop app.

Questions people ask first

Do I need an account?

No. There is no login, no email and nothing to sign up for. Yah Pro is a normal App Store purchase that works on your iPhone, iPad and Mac; if you bought it on one device, tap Restore on the others.

Do I need an API key?

No. Setup downloads a small on-device model — about 1.7 GB — and makes it the default: a model that can use the app's tools and runs on every supported iPhone. A Claude, Z.AI or DeepSeek key is optional; paste one under Settings → Cloud Models & API Keys only if you want a larger model.

Does it work offline?

Chat does. The default model is downloaded during setup, other models download the same way from Settings, and after that every chat runs on the phone with no network. Image generation, on-device dictation, Kokoro text-to-speech and video are local too. What needs a network is what reaches out by your choice: model downloads, web search, weather, a cloud key you pasted, connected mail, and the internet mesh. Nearby agents over Bluetooth or peer-to-peer Wi-Fi need no server at all.

What does the relay see?

Every message is sealed on your phone before it leaves, and the relay forwards what it cannot read. It does see who talks to whom, when, and how big the messages are — that is the caveat, stated in the same breath. There is intentionally no way to hand the relay an unsealed message. The long version is What the relay can and can't see.

Which iPhones?

Any iPhone that runs iOS 18.6; an iPhone 12 or newer is recommended. The app checks what your phone can handle and sizes things to fit: a phone with more memory runs larger models and holds longer conversations, and the newest phones run every model in the catalog at its highest quality.

What about iPad and Mac?

One purchase covers iPhone, iPad and Mac. Two carve-outs: Workout Quest and Apple Health are not on the Mac, and Kokoro neural voices are iOS-only — on the Mac the assistant speaks with Apple's built-in voices, and the app picks the most natural one installed.

When does the iOS app ship?

It is preparing for submission to the App Store. There is no date and no public test build; the waitlist is the one thing that will tell you, and joining it stores your email, the device you chose, the time you joined and your consent tick, nothing else.

Do my friends need Pro to talk to me?

Pro is per phone, and it covers what your own phone does on the internet: the hosted relay, pairing external agents, lobbies, and pairing a computer. Nearby chat between two phones over Bluetooth or local Wi-Fi is free for both of you. Connectors are free to install and never buy anything themselves; the phone that pairs them is what needs Pro.

Does the desktop app cost extra?

No. The desktop app and the Yah Desktop service are never sold separately; the phone is the system of record, and a Pro phone is what a computer pairs with.

Is Windows supported?

The Yah Desktop service installs on Windows with one PowerShell line and runs as a hidden logon task; the phone can pair and drive it. A Windows window is not in the installer yet. Connectors for all four platforms install on Windows the same way.

Can the relay read my messages?

No — it forwards what it cannot read, and it can only route between friends who have each added the other. See the question above for what it does see.

Where do chats, memory and the agent live?

On the device: your conversations, the agent's long-term memory — which you can open, read and delete note-by-note in Settings — and the downloaded models, which are kept out of iCloud backup. Deleting the app removes everything. The whole agent can be backed up to one file and restored on a new device.