Back to Browse

Agent Comms MCP Server

by ExaDev
Developer ToolsLow Risk9.2MCP RegistryLocal
Free

Server data from the Official MCP Registry

Cross-harness communication mesh for LLM agents — rooms, DMs, presence, and visibility over TCP

About

Cross-harness communication mesh for LLM agents — rooms, DMs, presence, and visibility over TCP

Security Report

9.2
Low Risk9.2Low Risk

Valid MCP server (1 strong, 1 medium validity signals). 1 known CVE in dependencies (0 critical, 1 high severity) Package registry verified. Imported from the Official MCP Registry. Trust signals: 8 highly-trusted packages.

10 files analyzed · 2 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "agent-comms": {
      "command": "npx",
      "args": [
        "-y",
        "agent-comms@10.0.16"
      ]
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

Agent Comms

GitHub npm Release CI

Cross-harness communication mesh for LLM agents: rooms, DMs, presence, and visibility over TCP with zero filesystem dependencies.

npm downloads chart, log scale GitHub stars chart, log scale

Why

LLM agents on the same machine are isolated silos. A Claude Code session cannot see a pi session running in the next terminal. A Codex agent cannot ask a Claude agent to review its work. Each harness manages its own context, tools, and state, with no shared communication layer between them.

Agent Comms gives them one. Any agent, in any harness, can register itself, discover other agents, join rooms, send direct messages, and coordinate work, all over a lightweight TCP mesh on localhost.

The project began as a filesystem-based bus (~/.agents/bus/), where agents read and wrote JSON files to communicate. This worked but brought real problems: orphaned files from crashed agents, polling overhead, concurrent write races, and complex stale-agent detection. The key insight that shaped the current design was that each MCP server instance is already a running process. The bridge processes themselves can form the mesh, with no daemon, no filesystem, and no polling.

How it works

Each bridge instance is a peer in a TCP mesh on localhost. The first instance to start binds the well-known port (19876) and introduces later instances to the mesh; peers also find each other through first contact on UDP. Every instance establishes direct data connections with every other peer, and one of them, elected by gossiped claim, holds the coordinator role that runs the machine's housekeeping.

graph LR
    subgraph Agent A ["Agent A (pi)"]
        A_LLM["LLM"]
        A_Bridge["pi bridge"]
    end
    subgraph Agent B ["Agent B (Claude Code)"]
        B_Bridge["Claude bridge"]
        B_LLM["LLM"]
    end
    A_LLM -- "agent_comms(send, ...)" --> A_Bridge
    A_Bridge -- "TCP localhost" --> B_Bridge
    B_Bridge -- "channel notification" --> B_LLM

All state is held in memory and synchronised between peers. Delivery events are pushed directly over TCP: no polling, no filesystem, no daemon process. Events that accumulate for an agent while its process is down are carried in the replicated delivery queues and replayed to it on return, so a restarted bridge is woken for what it missed rather than finding it only in history.

Coordinator pattern

sequenceDiagram
    participant P1 as Peer 1 (first to start)
    participant P2 as Peer 2
    participant P3 as Peer 3
    P1->>P1: binds port 19876, then claims the coordinator role once no holder has announced itself
    P2->>P1: connect to 19876
    P1-->>P2: peer list [P1]
    P2->>P1: establish data connection
    P3->>P1: connect to 19876
    P1-->>P3: peer list [P1, P2]
    P3->>P1: establish data connection
    P3->>P2: establish data connection
    Note over P1,P3: All peers now connected directly
    rect rgb(255, 230, 230)
        Note over P1: Port holder and coordinator is killed
        P2->>P3: lowest device-id claims the coordinator role at a raised term
        P2->>P2: race to bind 19876
        P3->>P3: race to bind 19876
        Note over P2,P3: the operating system's bind picks one port winner
        P3->>P2: loser re-introduces itself to the winner
    end
  • Well-known port 19876 on localhost: the compatibility first-contact address and introduction path, not the coordinator role
  • The first instance to bind it answers every later instance that connects there with the peer list; it is not a router
  • On graceful shutdown, the port holder names its longest-running peer as successor and hands the listener over before closing
  • On a crash, every surviving peer independently races to rebind the port; the operating system's exclusive bind picks the single winner, and the losers re-introduce themselves to it

Either way, direct peer-to-peer data connections are untouched, so messages between survivors keep flowing throughout, and first contact keeps finding peers while nothing answers the port.

The coordinator role is separate from the port. It carries the machine's single-authority duties: the stale-agent PID probe, the one offline announcement for a departed peer, and the default cc-peer front. It is held by claim rather than by binding anything, using wire-mesh's gossiped, term-based coordinator-frame: a higher term always supersedes a lower one, equal terms break by lowest device-id, and exactly one peer holds the role once the claims have spread. Claims travel only over sessions between peers on the same machine, since every duty the role carries is a fact about one machine.

  • A store claims the role only when it knows of no holder and is alone as far as it can tell: it bound the well-known port, or nothing on the port answered and it could not bind it either. When first contact is running, a holder that never held the port may still be about to announce itself, so the store first waits the ordinary network deadline for that announcement and claims only if none came; a store arriving at an existing mesh therefore never takes the role from its holder
  • Both ends of every session between two stores on the machine tell each other which claim they accept as the session opens, so a joiner learns the holder instead of claiming over it, whichever side dialled
  • Claims are read only from trusted sessions on the machine: never from a session that may cross machines (an addListener listener, a connectToRemote dial, or a dial at any address other than a loopback one, such as a peer first contact heard over LAN broadcast), and never from a session on the well-known port before it has introduced itself
  • Two meshes that each elected a holder while apart (joined later by first contact, say) converge on one: the lower claim is superseded and its holder stops its duties
  • When the holder departs, the survivor with the lowest device-id among the stores it has a session to claims at once at a raised term; any other survivor claims itself if, after the ordinary network deadline, the holder it accepts is still one it has no session to, which covers a successor that has gone too and a claim naming a device that never joined
  • The holder need not be the peer that bound the port, and a graceful shutdown hands on only the port listener: survivors recover the role from the departure itself

While the role is vacant, between the holder's loss and the successor's claim, no stale-agent probe runs and no cc-peer front is serving local Claude Code sessions that have no bridge of their own; the new holder restarts both as it takes the role. Every store's own session on the relay hub is unaffected, so messages from other machines keep arriving throughout.

First contact without a coordinator

The well-known port is one way for peers to find each other, not the only one. Every bridge also runs a small presence on UDP port 19877: it announces its own data port in a beacon (sent at start and every 30 seconds) and broadcasts one probe at start, which any peer that hears it answers with a fresh beacon so a newcomer does not wait for the next interval. A peer that hears a beacon dials the announced data port directly, and every established connection shares the peers it knows, so the connections form transitively with no rendezvous at all. A mesh therefore forms and heals whether or not anything answers the well-known port.

Beacons and probes go to a multicast group joined on the loopback interface (239.255.19.77) and to the limited broadcast address, never to a unicast address. Bridges on one machine share the same UDP port, and a unicast datagram to a shared port reaches only one of the sockets bound to it, so a reply addressed to a prober could land on the answerer instead. Loopback multicast reaches every bridge on the host whatever the state of the network, and broadcast reaches other machines on the LAN. A host whose loopback interface cannot carry multicast still discovers peers over broadcast, and reports the failure on the bridge's error channel.

Identity

Each bridge derives its peer ID from the device-id of its own keypair (SHA-256 of the raw public key): ECDSA P-256, self-signed, generated locally. The key material persists per bridge slot (~/.agent-comms/identity-<harness>--<cwd>.json, owner-only permissions), so the device-id, and with it the agent ID, room memberships, and peers' ability to keep delivering to the agent, survives restarts. Mesh state itself stays in-memory; the only thing on disk is the local key credential, the same trust model as an SSH key. A lock file guards the slot: a second live bridge in the same harness and directory runs with an ephemeral identity rather than duplicating the peer ID, and a stale lock self-heals by probing the recorded PID. The tokens an ephemeral bridge holds are bound to its throw-away key, so it keeps them in memory for the life of the process and never reads or writes the slot file. A slot file that exists but cannot be used (damaged, unreadable, or holding a key that cannot be certified again) is never replaced: the bridge stops with an error naming the file and why, and leaves it untouched, since a new key would change the peer ID for everyone who knows it and discard its room and group tokens. Restore the file from a backup, or move it aside to start a new identity.

Two more keys sit beside the slot files, each generated locally on first use and never derived from anything about the hardware. ~/.agent-comms/user-identity.json is the account's user principal, shared by every bridge the account runs on the machine. ~/.agent-comms/machine-identity.json is the machine, shared by every bridge the account runs on the host. Because it lives in the account's home directory, another OS account on the same host mints a machine key of its own and shows up as a separate machine, and until the principal can span hosts (#344) the two keys have the same scope; one machine key for every account on a host is tracked in #367. Both are grouping issuers: each bridge gossips a short-lived proof from each that vouches for its device, so a peer can tell whose device it is and which host it runs on. whoami shows them as the Principal: and Machine: lines, and list_agents groups agents under the machine that vouches for each, this machine first; an agent no current machine proof places, such as one that predates machine proofs, is listed under "Machine not proven". Moving a machine identity to a rebuilt host is a deliberate copy of its file, the same model as an SSH host key.

Breaking change (v2): earlier versions derived the peer ID from the SHA-256 fingerprint of the peer's self-signed X.509 certificate rather than its raw public key. The two values differ for the same keypair, so every agent ID, room membership, and pending delivery queue tied to a pre-v2 identity is orphaned on upgrade — there is no migration path, since existing peers can no longer address an upgraded one under its old ID. A v2 bridge cannot interoperate with a v1 one at all: they no longer agree on wire framing, transport, or peer identity.

Data directory

Set AGENT_COMMS_DATA_DIR before starting a bridge or an account command to keep its persistent mesh data in a separate directory. Unset or blank keeps ~/.agent-comms. The directory holds device, account and machine keys, identity locks, room and group tokens, gateway trust, connection codes, names, room-notice logs and the account grant ledger.

Environment and explicit directories must be absolute paths. Relative paths, literal ~ paths and empty explicit directories are rejected with an error naming AGENT_COMMS_DATA_DIR; they are never resolved against the working directory.

Library callers can set dataDir on IdentitySlot, which is also used by the identity loaders and lock helpers:

const slot = {
  harness: "my-bridge",
  cwd: process.cwd(),
  dataDir: config.dataDir,
};
const { store, tool } = await createBridgeMesh(slot);

An explicit dataDir wins over the environment and the existing slot.dir override. Without dataDir, slot.dir keeps its existing scope: device-slot files, trust and petnames; account and machine keys use the environment directory or the home-directory default. Bridges using the same data directory share the account and machine keys, while each harness/cwd keeps its own device key. Separate directories create separate identities; existing data is not copied or migrated. This is storage isolation: mesh ports, discovery and the hub are configured separately.

Install

pi

pi install npm:agent-comms

The pi manifest registers the extension automatically. It points at the TypeScript source, which pi loads without a build step, so the same entry serves pi install npm:agent-comms and pi install git:github.com/ExaDev/agent-comms; the npm package ships src for that reason. A git install has no build output, so the bridge, API and mesh work but the dashboard routes answer 503 naming the missing frontend build; the npm package includes the built dashboard.

The extension imports from @earendil-works/pi-coding-agent and @earendil-works/pi-ai, which the pi host provides, and its peer range requires 0.79.0 or later. The old @mariozechner/pi-coding-agent and @mariozechner/pi-ai packages are deprecated and unpatched, so a host still on that scope no longer satisfies the peer range; upgrade to @earendil-works/pi-coding-agent. A @mariozechner host at 0.73.1 was still able to load the migrated extension when the new packages were resolvable from its node_modules, but that is not a supported combination.

Claude Code

claude plugin marketplace add https://github.com/ExaDev/agent-comms
claude plugin install agent-comms@agent-comms

This repo serves as its own marketplace. The plugin manifest defines the MCP server.

Alternatively, register the MCP server directly with claude mcp add:

claude mcp add agent-comms -- npx -y agent-comms

A bare agent-comms serves MCP whenever its stdin is not a terminal, which is how an MCP client always launches it. npx -y agent-comms bridge mcp names the same server explicitly and keeps working.

Any MCP-compatible harness

Add to your MCP server configuration:

{
  "mcpServers": {
    "agent-comms": {
      "command": "npx",
      "args": ["agent-comms"]
    }
  }
}

The generic MCP bridge works with any MCP client. Incoming messages are included in every tool response. An explicit ["agent-comms", "bridge", "mcp"] is equivalent.

This server is also published to the MCP Registry as io.github.ExaDev/agent-comms.

Other harnesses

npx agent-comms                         # auto-detect harnesses and configure
npx agent-comms status                  # check current configuration
npx agent-comms remove                  # undo configuration

Or install as a dependency:

npm install agent-comms
pnpm add agent-comms

Or clone and build from source:

git clone https://github.com/ExaDev/agent-comms.git
cd agent-comms && pnpm install && pnpm build
npx agent-comms                         # auto-detect and configure

The CLI detects which harnesses are installed (pi, Claude Code, Codex, OpenCode) and writes the appropriate config files automatically.

cc-peer (cross-machine Claude Code relay)

cc-peer speaks Claude Code's own local cross-session peer protocol directly — a per-session Unix socket, no cross-machine leg of its own. The cc-peer bridge relays one local Claude Code session into this mesh, so it becomes visible and messageable from any other agent-comms bridge, including one on a different machine, riding on the mesh's own transport:

npx agent-comms bridge cc-peer <local-session-name>
# or address the local session by pid instead of its registered name:
npx agent-comms bridge cc-peer --pid=12345

One bridge process relays for exactly one local Claude Code session, the same "one bridge process is one agent is one device" model every other bridge here follows. Inbound messages from that session are posted into this bridge's own project room; mesh deliveries addressed to this bridge's agent are relayed back to that same session via cc-peer's own send().

Default cc-peer front

A Claude Code session with no agent-comms bridge of its own is still reachable from the mesh: whichever bridge on the machine currently holds the elected coordinator role fronts every local session it discovers via cc-peer's own roster, using the same (harness, cwd) identity slot that session's own claude-code bridge would use if it started. Identity belongs to the slot, not to whichever process is currently serving it. The session's own bridge holds the slot when it's live; the front holds it otherwise, and yields the moment a real bridge for that slot appears, so addressing, room membership, and queued deliveries all carry over unchanged across the transition. No configuration is needed: every bridge in this repo wires the front to its own coordinator-role transitions automatically, and a machine with no local Claude Code sessions (or no cc-peer sockets at all) runs it as a clean no-op.

cc-peer allows one peer per process, so bridge cc-peer lends its own peer to the front it runs as coordinator, and the front leaves that bridge's target session alone since the bridge already relays it.

Claude Code itself decides whether a message from another local process reaches a session. A bridge's messages arrive as peer messages, and when the sender's permission mode class differs from the receiving session's, Claude Code holds the message for the person at that session to approve ("Held peer message ... set "crossSessionInbound" to "accept""). Until they approve it or set crossSessionInbound to accept, nothing from the mesh reaches that session.

To accept those messages without approving each one, set crossSessionInbound to accept in user settings, ~/.claude/settings.json:

{ "crossSessionInbound": "accept" }

It can also be passed with the --settings flag or set in managed settings. A value in a project or local settings file is ignored, deliberately: the setting governs what reaches you, so a repository cannot turn it on for you. It needs Claude Code 2.1.224 or later. See the settings reference and Control inbound messages.

A session reached only through cc-peer has no agent-comms tool, so it can't call room_accept or room_reject. When a room join or a first-contact DM is waiting on it, the relayed message says which peer to message back and gives the two lines to choose from, accept <room> <requester> or reject <room> <requester> <optional reason>. The relay runs the matching action as that session's agent and messages the outcome back. Only a message from that session's own socket counts, so the person at the session is the one deciding.

The fronted session can reply, not just receive. A message with a single originating mesh agent (a DM or a room message) is delivered from that correspondent's own reply alias rather than from the front, via cc-peer's own AliasPool (the cc-peer/alias-pool subpath) — a real, natively-discoverable local peer, so the sender the session sees, and replies to, is the correspondent. The reply arrives back on that alias and the front turns it into a mesh DM to them. Nothing in the message body asks the session to do anything special, because replying to the sender is already the right move; an earlier version delivered from the front and named the alias in the text, which a model was free to ignore, and the reply then went to the front's own project room instead of the person who wrote (issue #284).

Aliases are created only on inbound contact from that correspondent, never pre-populated from the wider mesh roster, and are ephemeral: they live only in the front's own memory, so a restart drops them and the next inbound message from that correspondent re-materialises the same alias. A reply landing on an alias the front no longer recognises (e.g. after a restart) is reported back into the session as a clear error rather than silently dropped, as is a reply the mesh itself refuses to carry. If the alias cannot be started at all, the message still reaches the session, with a plain note that a reply to it cannot get back, and the failure is reported on the bridge's own error channel.

Working on the Rust workspace and the conformance corpus

conformance/ holds language-neutral test cases that every implementation of the package runs, and rust/ holds the Rust implementation of the package. A push that touches either, or the scripts and workflows that check them, runs scripts/rust-checks.sh from the pre-push hook, which needs rustup (the toolchain rust/rust-toolchain.toml pins is installed on first use) and Python 3.9 or later. Every cargo command goes through scripts/rust.sh, never cargo directly. The corpus format, how a case is added and what each field means are in conformance/README.md; a dependency is added to the Rust workspace by listing it, with the reason, in rust/deny.toml.

Adding a new harness

A bridge is two things:

  1. A tool, so the LLM can call agent_comms({ action: "send", ... })
  2. A push mechanism, so incoming delivery events reach the LLM's context

Core provides shared helpers so each bridge only implements those two things:

import {
  MeshStore,
  CommsTool,
  buildAction,
  ensureRegistered,
  formatDeliveryEvent,
} from "agent-comms";

const store = new MeshStore();
const tool = new CommsTool(store);

// 1. Initialise mesh and register identity
await store.init();
const { agentId } = await ensureRegistered({
  store,
  harness: "my-harness",
  defaultName: "my-agent",
});

// 2. Wire delivery callback for real-time push
store.onDelivery = (_targetId, event) => {
  const line = formatDeliveryEvent(event);
  yourHarness.push(`📬 ${line}`);
};

// 3. Wire tool into your harness
const action = buildAction(paramsFromToolCall);
const result = await tool.handle(
  { agentId, harness: "my-harness", cwd: process.cwd(), pid: process.pid },
  action,
);

See src/bridges/ for working examples.

Usage

# Register yourself
agent_comms({ action: "register", name: "vault-refactor", visibility: "visible", tags: ["obsidian"] })

# List other agents
agent_comms({ action: "list_agents" })

# Create a room
agent_comms({ action: "create_room", room: "code-review", type: "public", description: "Cross-harness review" })

# Join an existing room
agent_comms({ action: "join_room", room: "general" })

# Send a message
agent_comms({ action: "send", target: "code-review", content: "Batch 3 done." })

# Send with delivery timing hint
agent_comms({ action: "send", target: "code-review", content: "Review needed now.", streamingBehavior: "steer" })

# DM another agent
agent_comms({ action: "dm", target: "a1b2c3", content: "Can you review my last commit?" })

# DM with delivery timing hint
agent_comms({ action: "dm", target: "a1b2c3", content: "Urgent: deploy is blocked.", streamingBehavior: "steer" })

# Read room history
agent_comms({ action: "read_room", room: "general" })

# Go dark
agent_comms({ action: "update", visibility: "hidden" })

Delivery timing

send and dm accept an optional streamingBehavior field that tells the receiving bridge how urgently to surface the message:

ValueMeaningPi bridgeClaude Code bridgeDrain bridges (MCP, Codex)
steerAct now — react at the next decision boundarydeliverAs: "steer"[STEER] prefix + meta.streamingBehavior[STEER] prefix on drain
followUpAct when idle — wait until the current task finishesdeliverAs: "followUp"[FOLLOWUP] prefix + meta.streamingBehavior[FOLLOWUP] prefix on drain
infoWhenever convenient (default, matches current behaviour)Informational bufferNo prefixNo prefix

When streamingBehavior is absent, each bridge falls back to its existing heuristic: actionable events (DMs, room messages, invites) are treated as steer; status changes and membership events are treated as info.

Claude Code delivery mechanism: Events are written to ~/.agents/bus/pending/claude-code--<cwd-slug>.jsonl. Three Claude Code hooks (PostToolUse, Stop, UserPromptSubmit) invoke hooks/drain.sh, which atomically renames the file, writes its content to stderr, and exits 2. Claude Code's asyncRewake mechanism wraps the stderr in a <system-reminder> and wakes idle Claude. When the agent_comms tool is called directly, the tool handler drains the same file via the same atomic rename — concurrent drains never duplicate because rename is the synchronisation primitive. The [STEER] and [FOLLOWUP] markers and meta.streamingBehavior carry timing intent; acting on them is down to the receiving agent. The pi bridge honours the hint natively via deliverAs.

Web UI

Any bridge that starts a web server (npx agent-comms chat, or any other command that brings one up) serves a small browser dashboard alongside its REST API: agent and room lists, message history, a live mesh graph. The dashboard runs inside a SharedWorker, shared by every tab open against that bridge, so several tabs see one consistent view instead of each opening its own separate connection into the mesh.

A bridge's web server binds the first free TCP port from 19877 to 19886, so several bridges on one machine each get a port of their own in that range, and takes a port the operating system picks only when all ten are taken. The hosted dashboard looks for a bridge on those same ports, which is how it finds one without being told a port. The address a bridge prints, and the web_url action returns, is the port it actually holds.

The dashboard page carries a content security policy (a meta tag, since a static host sets no headers): it denies everything by default, allows script only from its own origin, and allows connections only to its own origin and to 127.0.0.1 and localhost. The policy binds the page. The shared worker that holds the bridge connection takes its policy from its own script's response headers, which a static host does not set, so the worker is not bound by it; and a policy in a meta tag cannot forbid the page being framed, which needs a response header. Its service worker answers a page navigation from the network while the host is reachable and from its cache only when the host cannot be reached, so a redirect the host answers is always followed. The origin the hosted dashboard is served from is defined once, in src/bridges/user/web/hosted-dashboard.ts.

Two independent transports sit inside that dashboard, both built on oRPC, a contract-first RPC layer with Zod-validated inputs and outputs and native support for streaming procedures:

  • Worker ↔ server, over a real WebSocket at /ws/mesh. The worker is an oRPC client here, calling the same contract procedures the REST API exposes, plus a subscribeEvents procedure that streams mesh events as they happen.
  • Tab ↔ worker, over a MessagePort. The worker flips role for this leg and acts as the oRPC server, implementing the same contract (plus a disconnect procedure for tab teardown) for each tab that connects to it.

Both legs are independently resumable: each side of the worker keeps its own buffered, replayable event stream tagged with event ids, so a tab that briefly loses its MessagePort connection, or a worker whose upstream WebSocket drops, picks back up from its own last-seen event rather than missing whatever happened while it was disconnected. This is distinct from the mesh-level deliveryQueues mechanism described under "How it works" above, which covers an agent bridge process restarting — a browser tab going away and coming back, or a worker's own socket dropping, is a different failure mode with its own resumable stream. An event id names the publisher's instance as well as the event, so an id from before a restart, or one older than the events still kept, is recognised as unusable: the subscriber then starts from a fresh state_sync snapshot instead of from a replay that would repeat or skip events.

Not every piece of dashboard data travels over that live event stream, though. Agents and rooms do — every change arrives as a patch the instant it happens, so there's nothing to separately fetch. Room message history, the mesh's connection graph, and a path trace are different: genuine one-shot request/response reads with no ongoing subscription of their own. Those three go through TanStack Query, wired up via oRPC's own TanStack Query integration over the same tab-to-worker oRPC client described above — caching, request de-duplication, and cache invalidation on the same events that already drive the live side of the dashboard.

Pairing the hosted dashboard

The dashboard that GitHub Pages serves reaches a bridge on the same machine. The origin it is served from is shared by every page published under the same account, so the origin alone does not say which page is calling, and a port in the bridge range does not say which listener is the bridge. A per-install pairing secret, which this bridge issued and never sends, settles both: the dashboard and the bridge each prove they hold it before the dashboard sends anything or the bridge admits anything. A dashboard served by the bridge itself, and any other client on this machine, needs no secret.

To pair a browser, open http://127.0.0.1:<port>/pair (the bridge prints the address when it starts; the first bridge is on port 19877) in that browser on the machine running the bridge, and press Pair this browser. That opens the hosted dashboard with the secret in the address fragment, which no server receives. The dashboard keeps it in its own storage and removes it from the address. A browser without a secret is shown how to pair instead of being offered a connection.

The secret is only ever the key of a proof. For each port of the range the dashboard opens /ws/hello and sends a fresh random nonce, and nothing else. A bridge answers with its own nonce and an HMAC-SHA-256 over its role, both nonces and the port, keyed with the secret. The dashboard checks that proof in constant time and, only if it is right, answers with its own over the same nonces under the other role; a listener that is not the bridge learns one nonce and is not spoken to again, and a proof is bound to the port it was made for, so a listener cannot pass the real bridge's answer off as its own. The bridge checks the dashboard's proof and answers with a single-use ticket that lives a few seconds. The dashboard offers the ticket on the mesh socket as a second subprotocol (agent-comms-ticket.<ticket>), since a browser cannot set headers on a WebSocket and a query string would put the ticket in logs, and the server always selects the fixed agent-comms subprotocol, so the ticket is never echoed. A page of the hosted origin reaches nothing else of the bridge: every HTTP route and every other path answer 403.

The secret is 256 random bits from the platform's cryptographic random source, kept as web-pairing-secret in the data directory with owner-only permissions (a file that is open to anyone else, or that belongs to someone else, is replaced), and never placed in a URL query string, a header or a log. agent-comms pairing rotate replaces it: the running bridge reads the file again when it changes, so every ticket and proof under the old secret is refused at once, without a restart, and every socket the hosted dashboard holds open is closed as soon as the operating system reports the secret file replaced (a periodic check once a second ends it otherwise, where the file system reports nothing); each browser pairs again. The pairing page is served only to a client on this machine, never to a page of the hosted origin and never to a request another site started, and it cannot be framed.

The dashboard keeps the secret in the storage of its own origin, which every page of that origin can read, so pairing separates a browser profile that was never paired from one that was, not pages that share the dashboard's storage; separating those needs the dashboard on an origin of its own. The exchange is a change to both sides: a dashboard that has it cannot connect to a bridge from before it, and a bridge that has it refuses a dashboard from before it. Update the bridge, and reload the dashboard, to the latest release of each.

Reaching the web UI from the LAN

A bridge's web server listens on loopback only unless told otherwise, and a browser on the same machine needs no credentials. To open the dashboard (and the optional wire-mesh console) from another device on the network, set AGENT_COMMS_WEB_HOST to the IP address to bind before starting the bridge: 0.0.0.0 (or ::) for every interface, or one interface's own address to expose only that network. A value that is not an IP address stops the server from starting rather than falling back to loopback.

AGENT_COMMS_WEB_HOST=0.0.0.0 npx agent-comms chat

The server exposes every mutating action (POST /api/action and the /ws/mesh socket), so a bind beyond loopback always comes with a per-process secret token, generated at start and printed once to stderr (never stdout, which can be an MCP channel) as ready-to-open URLs of the form http://<address>:<port>/?token=<token>. Every client not on this machine must present it, as an Authorization: Bearer <token> header or as the cookie that opening the URL sets (the server then redirects to the same path without the token, so it does not stay in the address bar). The cookie is named agent_comms_web_token_<port>, because browsers scope cookies to a host and not a port, and two bridges on one machine each have their own token. Requests without the token get 401 and the comparison is constant-time. A client on this machine, meaning loopback or one of this machine's own interface addresses, needs no token, so the web_url an agent is given works even for a server bound to one interface address. Every request from every client, loopback included, must carry a Host header naming an address the server is bound to, a loopback name or this machine's own name, which blocks DNS rebinding; any Origin header, from any client and loopback included, must name the server itself over http, which blocks cross-site requests and cross-site WebSocket hijacking from a page open in the operator's own browser (the server sends no CORS headers). The one exception is the dashboard hosted on GitHub Pages, which reaches a local bridge by probing loopback ports: its origin is admitted from a client on this machine only. The access cookie is SameSite=Lax, so opening the printed URL from a link on another site still sets it; Lax cookies are not sent on cross-site POSTs or WebSocket upgrades, and the Origin check covers the rest. The token lives in memory and changes on every start. A request body and a WebSocket message are limited to one mebibyte (the largest legitimate request is a chat message a person typed or pasted): a larger body is answered 413 and the connection closed, and a larger socket message closes that socket with status 1009. A body that is not a JSON object (an array included) is answered 400, a route whose work fails is answered 500 with fixed text, a request not completely received in the time a body of the largest size takes at a slow but steady rate (thirty-two seconds) is answered 408 and its connection closed, which Node checks at intervals of thirty seconds, so the answer comes within about a minute of the request starting, and an upgraded WebSocket is not subject to it, every response forbids content sniffing, and no request can end the bridge. The content of a message sent through the tool's send or dm action has the same limit, counted in UTF-8 bytes, and a longer one is refused before anything is sent. A relay a bridge serves accepts a WebSocket message of at most 16 MiB, which is above the largest frame a conforming peer sends; a larger one closes that connection with status 1009 and nothing else. No client of the relay is held open without a deadline: a request that is not a WebSocket upgrade is answered 426 and its connection closed, a request whose headers or body stop arriving is cut off after ten seconds (answered 408 where Node can), and a WebSocket that has not gossiped an advert for an admitted device within thirty seconds is closed.

Plain http also means the token, and everything the dashboard shows or sends, crosses the network unencrypted: anyone who can observe traffic on that network segment can read the token and then act as the operator. Bind to an interface address on a network you trust (a home or office LAN, a private Tailscale interface address) rather than to 0.0.0.0 on a shared or public network. A reverse proxy running on the same machine reaches the server from loopback and so counts as a client on this machine: it bypasses the token check, which leaves the proxy's own authentication as the only protection, although the Host check still applies.

Plain http and ws are what the LAN path uses, so a page served over https (the hosted mesh.exadev.io instance) cannot dial it; open the bridge's own address instead. A bridge that binds beyond loopback also broadcasts a small agent-comms-web-beacon datagram on the first-contact port (19877) carrying its peer id and web port; the receiver takes the host from the datagram's source address, and the token is never advertised.

The other bridges on the network hear those beacons. lan_web_uis lists every neighbouring web UI heard this way, each as a ready-to-open http://<address>:<port> URL beside the full peer id and its names. An entry drops out again once its bridge has missed a few beacon intervals, so a dashboard that has gone away leaves the list rather than lingering.

Alternate UI: wire-mesh's web-console

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!