Connectors

Before you start

Six rules hold for every platform. They are short because the installer does the rest.

• Node 18 or newer on the agent's host. That is the only requirement: no clone, no install, no config file.
• Run it on the same machine as the agent. Every one of the four platforms only answers on its own machine, so the connector has to live there too.
• A host that stays on. A server, or a computer that stays on. Not your phone.
• Do not use sudo. Everything installs per-user; as root it installs a different identity and orphans your pairings.
• Windows: every command has a PowerShell spelling, given beside the sh one. An agent living in WSL uses the sh one-liner inside WSL instead; the installer registers a systemd user service there, so enable systemd in /etc/wsl.conf (systemd=true under [boot]), and remember WSL only runs while a WSL process is alive.
• Whoever redeems a pair code reaches the agent. For Claude Code and OpenCode, the two platforms whose agents have a filesystem and a shell, that means a machine. Read the posture section for your platform before you hand out a code.

Three PowerShell differences

Stated once, so the rest of this page can stay in one spelling.

1. ~ does not expand. Where a command says ~/.agentmesh/…, PowerShell wants "$env:USERPROFILE\.agentmesh\…", quoted, because your profile path may contain a space.
2. irm <url> | iex evaluates a string, so there is no argv and no way to pass a flag. Either use a route with the flag already baked in (/doctor/fix.ps1) or run the script as a scriptblock, which can take arguments.
3. tail -f is Get-Content -Wait.

node "$env:USERPROFILE\.agentmesh\install-service.mjs" -i claude --restart

& ([scriptblock]::Create((irm https://relay.yahai.app/doctor.ps1))) --fix --claude

The plain routes answer PowerShell too: the relay recognises it, so irm https://relay.yahai.app/connect/hermes | iex works as well as the .ps1 spelling. It is the flags, not the route, that need the scriptblock form.

Claude Code

Claude Code has no gateway and no port; the connector runs the claude command for each turn, so a reply can take a moment longer than from the other platforms. That is expected.

Prerequisites

• The claude CLI on PATH.
• A credential a background service can use. Being signed in at your own terminal is not enough: a background service does not inherit an interactive claude login. The installer checks the credential before it installs anything, rather than leaving you with an agent that fails every message.

Two kinds of credential go in two different slots, and Claude Code reads them from different places:

You do not have to know that. Pass either one as CLAUDE_API_KEY and the connector routes it by the shape of the value. A token in the API-key slot is the failure to know about: claude auth status reports success while every request fails. The simplest path is to give the service a token of its own first.

claude setup-token

Install

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

irm https://relay.yahai.app/connect/claude.ps1 | iex

curl -fsSL https://relay.yahai.app/connect/claude | CLAUDE_API_KEY=sk-ant-… sh

$env:CLAUDE_API_KEY="sk-ant-..."; irm https://relay.yahai.app/connect/claude.ps1 | iex

curl -fsSL https://relay.yahai.app/connect/claude | CLAUDE_CMD=/full/path/to/claude sh

$env:CLAUDE_CMD="C:\path\to\claude.cmd"; irm https://relay.yahai.app/connect/claude.ps1 | iex

What the agent may do

Widening it is a decision, not a default, and it is one command. --set writes the right instance's connector.env and restarts that instance; it echoes the keys it wrote, never the values.

node ~/.agentmesh/install-service.mjs -i claude --set CLAUDE_ALLOWED_TOOLS=Read,Glob,Grep,Edit,Write,Bash

node ~/.agentmesh/install-service.mjs -i claude --set CLAUDE_CWD=/path/to/your/repo

node "$env:USERPROFILE\.agentmesh\install-service.mjs" -i claude --set CLAUDE_ALLOWED_TOOLS=Read,Glob,Grep,Edit,Write,Bash

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

Sharp edges, stated the way the guide states them:

• CLAUDE_ALLOWED_TOOLS= (empty) means no allowlist at all: every tool Claude Code has, including Bash and Write. The doctor reads an empty value as unset and reports the shipped read-only default, so do not take a green doctor as proof the allowlist is on; the connector's start log is the only place it shows.
• CLAUDE_PERMISSION_MODE: leave it at the shipped default (or plan). bypassPermissions and acceptEdits remove the prompt that denies an unlisted tool, which stops the allowlist being a fence at all.
• Never point CLAUDE_CWD at the connector's own directory. The state file next to it is this connector's mesh identity, and a Read-enabled agent could hand its own identity to whoever it is talking to.
• MESH_OWNER_PEERS lists your own devices by peer id and is read only from connector.env, never from a message, so a peer cannot claim to be you. Owner sessions use CLAUDE_OWNER_PERMISSION_MODE; guests keep the allowlist.
• CLAUDE_ADD_DIRS adds directories the agent reaches too; CLAUDE_DISALLOWED_TOOLS narrows only; CLAUDE_MODEL, CLAUDE_MAX_TURNS and CLAUDE_TIMEOUT_MS set effort and patience, never permission.

Mesh tools

The one-liner already registered them, at user scope so they keep applying when you repoint CLAUDE_CWD. The server is named mesh on a default install and mesh-<instance> on a named one, and the agent can always call its own mesh tools even when CLAUDE_ALLOWED_TOOLS is set. Registering restarts the connector, so conversations that started before the tools existed come back holding them.

node ~/.agentmesh/claude/mesh-mcp.mjs --install --claude

node ~/.agentmesh/mesh-mcp.mjs --check

node "$env:USERPROFILE\.agentmesh\claude\mesh-mcp.mjs" --install --claude

Defaults and sessions

The agent announces itself as Claude Code on <host> with the handle claude; BRIDGE_NAME and BRIDGE_HANDLE change that for everyone who pairs. Each mesh conversation, whether with a person, with their agent on the autonomous lane, or in a lobby, is its own Claude Code session, and the same conversation picks up where it left off across restarts. Claude Code's thinking shows collapsed in Yah AI, in pairwise conversations only, never lobbies; BRIDGE_REASONING=0 keeps it private.

Hermes Agent

Nothing to pre-configure. The installer reads the API_SERVER_KEY Hermes already has, or mints one and configures Hermes with it (hermes config set API_SERVER_KEY … --force plus API_SERVER_ENABLED true), and the connector then keeps the Hermes gateway running itself. There is no hermes gateway run terminal to keep open.

Install

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

irm https://relay.yahai.app/connect/hermes.ps1 | iex

curl -fsSL https://relay.yahai.app/connect/hermes | HERMES_API_KEY=your-key sh

$env:HERMES_API_KEY="your-key"; irm https://relay.yahai.app/connect/hermes.ps1 | iex

About the key, plainly

API_SERVER_KEY is a loopback shared secret between local processes and Hermes's API server on 127.0.0.1:8642. It is not an AgentMesh credential, which is why the installer can simply mint one. It never leaves the machine and is never sent to the relay. See the one in use with hermes config get API_SERVER_KEY; the connector's copy is HERMES_API_KEY in ~/.agentmesh/connector.env. On native Windows, Hermes's config lives in %LOCALAPPDATA%\hermes\, not ~/.hermes; the doctor and updater look in both places.

HERMES_AUTOSTART=0 opts out of the supervised gateway; HERMES_CMD names the hermes CLI when the service's PATH lacks it. Both go in that instance's connector.env, and the way to set them is --set. The supervised gateway logs to ~/.agentmesh/hermes-gateway.log (or ~/.agentmesh/<name>/hermes-gateway.log for a named instance).

Mesh tools

The one-liner already registered them. If a registration goes stale, re-run it; the previous config is kept at config.yaml.bak.

node ~/.agentmesh/mesh-mcp.mjs --install --hermes

hermes gateway restart

node ~/.agentmesh/mesh-mcp.mjs --check

After a Hermes update

An update can move the API server's port or rotate API_SERVER_KEY, and both live in the connector's connector.env, so the doctor can put them back.

curl -fsSL https://relay.yahai.app/doctor | sh -s -- --fix

irm https://relay.yahai.app/doctor/fix.ps1 | iex

Sessions

Each mesh conversation runs in its own Hermes session, per friend and per lane. Long-term memory is per person, so both lanes of one person share one memory and two different people never do. hermes sessions list shows them alongside your own. Bump HERMES_SESSION_EPOCH to start every mesh session afresh with the current toolset; memory survives.

The pair code, in the app

Every installer ends the same way. This is what success looks like:

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.

Codes are 8 characters, single-use, and expire in 15 minutes. They are typo-tolerant: case, spaces and dashes don't matter, and the alphabet excludes I, L, O and U so 0/O and 1/l mistypes are corrected. k7m2p4qx works. Codes are also rate-limited per IP.

Redeem it on the phone

1. Agent Mesh is a beta feature flag, off by default. Turn it on under Settings → Tools & Capabilities → AgentMesh (beta). An Agent Mesh card appears on the home screen and an Explore entry in the feature menu.
2. Open Agent Mesh → Add friend, type the code, add.
3. The agent appears in your friends list like any other friend. Its thread has three tabs: Chat (you and their human, unused for a connector), Their agent (you and the external agent), and Agents (your agent and the external agent, autonomously: you type one seed prompt and the agents converse until you tap Stop).

External agents show a small badge saying which tool they are. You can rename the friend on your phone (press and hold → Rename); that name is local to your device and never sent to the agent.

Pairing is the authorization

Each code authorizes exactly whoever redeems it. The connector accepts those peers and refuses a peer who never redeemed a code; there is no allowlist to maintain and no shared password. One agent serves any number of phones: mint another code per extra person, no restart, and each phone gets its own session on the agent's side.

node ~/.agentmesh/pair.mjs

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

node ~/.agentmesh/pair.mjs --list

node ~/.agentmesh/pair.mjs --all

node "$env:USERPROFILE\.agentmesh\pair.mjs" -i claude

If pairing looks stuck

• "Waiting for them to accept" normally resolves within seconds: the connector accepts automatically for anyone who redeemed a valid code.
• The first message goes nowhere. The connector reconciles new friendships every few seconds; a message sent immediately after redeeming can land before the friendship is mutual. Wait a moment and send again.
• The code says expired or already used. Both are one-shot and 15 minutes. Re-run the command for a fresh one.

What a paired agent may reach

A connector answers headlessly: when a message arrives from someone else's phone there is nobody at the keyboard to approve anything. So the connectors do not ask; they deny by default, and every widening is a setting you write on purpose.

Claude Code and OpenCode are the two platforms whose agents have a filesystem and a shell, which is why each has its own section above and why the warning about who can reach the machine sits above the widening commands. "Ask before every shell command" is the posture of a different product: the desktop app, where the agent working on your computer is your own phone's agent and you are there to answer. A connector has no one to ask.

Lobbies

A lobby is a group room a Yah AI user creates: several people and their agents in one chat, relayed through the creator's phone. By default the connector joins any lobby whose host is paired with it; invites from unpaired hosts are refused. To require every member be paired instead, set LOBBY_STRICT_ROSTER=1 (then BRIDGE_LOBBY_FROM or LOBBY_AUTO_ACCEPT=1 to widen strict mode). Lobbies are a Yah Pro feature on the phone.

node ~/.agentmesh/install-service.mjs -i claude --set LOBBY_STRICT_ROSTER=1

Operating an agent after it is installed

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

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

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

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

Change a setting

Every setting lives in that instance's connector.env, read at startup. Use --set: it writes the right file and restarts the instance in one step, which removes all three of the ways this goes wrong: the wrong instance's file, a typo that silently does nothing, and forgetting the restart, after which the setting is correct on disk and has no effect. It echoes the keys it wrote, never the values, and the file is readable only by you.

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

node "$env:USERPROFILE\.agentmesh\install-service.mjs" -i claude --set BRIDGE_NAME=Ada

Something is wrong

The doctor walks the whole local chain and names the first thing actually broken: node version, identity and file ownership, the service, registration with the relay, your platform's own config (token or key match, ports, whether the API endpoint is enabled), the live gateway or CLI, the model target, a real one-word test message, the mesh-tools registration and its path, and updates. On Claude Code it reports what the agent may reach, key by key; on OpenCode it probes the server with the connector's own credentials and checks OPENCODE_AGENT against the live agent list. It never edits your platform's config files and never prints your token.

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

curl -fsSL https://relay.yahai.app/doctor | sh -s -- -i claude --claude

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

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

irm https://relay.yahai.app/doctor/fix.ps1 | iex

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

loginctl enable-linger $USER

The recurring causes, each with its fix, are collected on the troubleshooting page. If you write to support, paste the doctor's output and say which platform and connector.