Coordinate apps on one machine

Let MainSDK apps on the same host share attack and pressure signals over a local bus, and ask a declared peer for its status.

Building for 0.4

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

You will turn on the host bus for an app, choose what it hears and shares, and check it from the command line. It takes about 10 minutes. The bus is local to one machine and one OS user.

You need

Two or more MainSDK apps on the same machine, with apps.registry: on.

1. Join the bus

main.yaml

apps:
  registry: on
neighbours:
  host: on
  listen: [attack.*, pressure.*]
  share: [attack.suspected, pressure.high]
  priority: 5

Anything not in share stays inside the app (MAIN-NEIGHBOUR-0007).

2. Hear the neighbours

app/signals.ts

import { signals } from "mainsdk";

signals.on("attack.*", (s) => console.log(s.name, s.source.project, s.trust), { from: ["host"] });

Host signals reach handlers only when you ask for them with from.

3. Check the bus

bash

npx mainsdk neighbours

It prints the host bus settings, this app's socket name and the last host signals. To change the shared key, run npx mainsdk neighbours rotate-key; running apps re-read it within 60 seconds.

4. Ask a peer

List the peer under apps.peers with apps.link: on, accept the verb under neighbours.asks.accept, then:

import { neighbours } from "mainsdk";

const status = await neighbours.ask("prj_01JD8X", "status");

Check it worked

mainsdk neighbours shows the socket and, after a neighbour shares a signal, that signal under the last host signals.

Troubleshooting

MAIN-NEIGHBOUR-0001: a bad value, or host: on with apps.registry: off.
MAIN-NEIGHBOUR-0002: the host key or folder is unsafe. The bus stays off and the app keeps serving. It stays off on Windows.
MAIN-NEIGHBOUR-0004: an ask was refused. Check asks.accept and the peer lists.

See the neighbours interface and signals.

Was this page helpful?