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 was copied from it or from the pairing guides in the repository, and the source is named in the page's HTML.

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 the sha256 of every artifact 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 verified against that hash 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 session epoch is bumped, so conversations are reborn with the new tools; memory survives.
• On OpenCode, the connector's detached server is retired 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 has check_for_updates. 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 the relay's lastSeen for that identity:

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. Registration republishes the identity, and a connector started before a relay change can hold a stale directory record; current builds re-register every 5 minutes on their own, 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: it writes your edge only, and the relay forwards nothing until both sides list each other. 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 Code

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 discovers the machine over Bonjour (_yahcode-orchestrator._tcp) 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 Code, both devices must be on the same Wi-Fi and the Yah Code 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 directly from the service's loopback API, 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. bun install compiles llama.cpp the first time, so the machine can run a local planner model with no network. Later reinstalls reuse it.

"There is no Windows window"

On Windows the installer sets up the Yah Code service as a hidden logon task; the native WinUI window ships in the source tree and builds on the machine with Visual Studio. 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/: paired.json (the phone's pairing token), orchestrator.json, workspace.json, models/ and logs/. The installed payload 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 no server-side user table. Apple is the account: Yah Pro is a StoreKit 2 purchase verified on the device, and Restore brings it to your Apple ID's other devices.

Do I need an API key?

No. Setup downloads Liquid AI's LFM2.5 2.6B · Agentic from Hugging Face — about 1.7 GB — and makes it the default: a tool-calling model with a 128K-token window that 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, LFM2.5 2.6B, is downloaded from Hugging Face during setup as a GGUF file — nothing is bundled in the binary; other models download the same way from Settings — and after that every chat inference runs on the device with llama.cpp, with no network. Image generation with Stable Diffusion, on-device dictation, Kokoro text-to-speech and video synthesis 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?

Before a frame leaves the device it is sealed with X25519, HKDF-SHA256 and ChaChaPoly, with a fresh nonce per frame. The relay stores public keys, friend edges, signed listings and sealed mailboxes, and it forwards ciphertext 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 endpoint that accepts plaintext. The long version is What the relay can and can't see.

Which iPhones?

iPhone 12 and newer, on iOS 18.6 or later. The phone's tier sets the context window and the model ceiling: 4 GB phones (iPhone 12, 12 Pro, 13, 13 mini, SE 3) get a 2K context and models up to 2.2 GB; 6 GB phones (13 Pro, 14, 14 Pro, 15) get 4K and 3.0 GB; A17 Pro and 8 GB devices (15 Pro, 16, 16 Plus, 16e, 16 Pro, 16 Pro Max) get 8K and 4.5 GB, and an A18 Pro runs every model in the catalog at its highest quality. A phone newer than the iPhone 16 family — the iPhone 17 family, which the app's chip map does not yet name — falls back to the app's chip-and-memory detection: with 8 GB it is classed with the A17 Pro and gets the 8K context and the 4.5 GB ceiling. Context is sized from the model's own KV-cache geometry against real free memory, up to a 64K ceiling, so a long-context model — the default LFM2.5 2.6B supports 128K — is not pinned to the tier number on a phone with room.

What about iPad and Mac?

One purchase covers iPhone, iPad and Mac through Universal Purchase; the same code ships to all three. 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 Yah Code 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 Code service installs on Windows with one PowerShell line and runs as a hidden logon task; the phone can pair and drive it. The native window builds from source with Visual Studio. Connectors for all four platforms install on Windows the same way.

Can the relay read my messages?

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

Where do chats, memory and the agent live?

On the device: conversations in Core Data, the agent's long-term memory as Markdown files you can inspect note-by-note in Settings, downloaded models under Application Support and excluded from iCloud backup. Deleting the app removes everything. The whole agent can be exported to one JSON file and imported on a new device.