neuralOS A2A Mesh — deploy, operate, troubleshoot
An end-to-end agent-to-agent (A2A) messaging system built from three
layers that this skill wires together:
| Layer |
Component |
What it provides |
| Transport |
NATS / Synapse subjects |
request/reply, pub/sub, JetStream durability, leaf nodes across networks |
| Trust + routing |
reactorpro-gateway (v1.7.5+) |
Ed25519-signed envelopes, fingerprint pins, invoke + skillproxy lanes, REST/UI on :3000 |
| Intelligence |
neuralOS / needle engine |
offline 121M tool-calling model that grounds every butler query to a read-only probe |
Every remote action is: question in → engine selects a probe → read-only
execution → small capped digest back over a signed envelope. There is no
keyword-only fallback in the serving path.
The one rule
Every requirement is either already given or you must ask for it. Never
invent a NATS URL, account, credential, fingerprint, service account, path or
port. Run the intake in references/parameters.md before installing anything;
if a required value is missing, request it from the operator and wait.
Workflow
- Intake — read
references/parameters.md, collect every REQUIRED
parameter (central NATS server, per-edge identity, creds, pins, ports,
service accounts, engine dir, butler skills). Ask for anything missing.
- Design the topology — pick from
references/architecture.md
(single edge → two-edge → three-edge → multi-country hub-and-spoke with
leaf nodes). Confirm the shape with the operator.
- Install per host — follow
references/install.md for macOS, Linux and
Windows (engine, gateway, butler harness, service wiring, verification).
- Wire trust — exchange fingerprints out of band, set mutual
LIVEAGENT_GATEWAY_MESH_TRUSTED_PEERS, -mesh-verify-mode=require,
-mesh-trust-on-first-use=false on every edge.
- Stand up a butler — use
references/butler-harness.md and
scripts/butler_template.py; mandatory needle grounding, read-only probes,
honest holes.
- Verify end to end — run
scripts/doctor.sh / doctor.ps1, then a
never-seen-before benchmark from at least two origins
(scripts/dispatch.sh). Do not sign off without it.
- Operate —
references/operate.md (health, upgrades, rollback, reboot
survival, capacity, key/credential rotation, adding an edge or skill).
- Troubleshoot —
references/troubleshooting.md when anything fails;
work top-down: transport → trust → gateway → butler → engine → data.
References (one hop, load on demand)
| File |
Read when |
references/architecture.md |
designing the topology; envelope/subject/trust semantics; leaf nodes and cross-org |
references/parameters.md |
before every install — the full intake questionnaire + central NATS server parameters |
references/install.md |
installing engine/gateway/butler on macOS, Linux or Windows; service wiring |
references/butler-harness.md |
writing or extending a butler skill; menu design; skillproxy contract |
references/operate.md |
day-2: health, benchmarks, upgrades, rotation, reboot survival, new edges |
references/troubleshooting.md |
any failure — connection, TLS, permissions, trust, engine selection, cross-platform |
references/examples.md |
simple → complex worked examples end to end, including the Africa multi-country playbook |
Scripts
| Script |
Purpose |
scripts/doctor.sh / doctor.ps1 |
full environment + connectivity diagnostic; prints a pass/fail report |
scripts/dispatch.sh / dispatch.ps1 |
call a remote butler through the signed skillproxy lane; measures wall time |
scripts/butler_template.py |
cross-platform butler harness: ask.py retrieval → needle → read-only probe → capped digest |
scripts/bootstrap_edge.sh / bootstrap_edge.ps1 |
install engine + gateway + butler as a reboot-surviving service |
scripts/nats_central.conf |
central cloud NATS server template (TLS, accounts, JetStream, leaf-node acceptor) |
scripts/nats_edge.conf |
edge/client-side NATS config + leaf-node remote template |
Run a script with the platform's shell: bash scripts/doctor.sh,
pwsh -File scripts\doctor.ps1. Scripts read parameters from environment
variables and say exactly which are missing.
Non-negotiable constitution
- Mandatory needle grounding. Every butler query routes through the
on-device engine. No deterministic keyword fallback in the serving path.
- Read-only probes. Buttlers execute only probes from their
needle_menu.json. No writes, no arbitrary shell, no credentials.
- Honest holes. Upstream failure ⇒ relay the error verbatim. No probe
selected ⇒ say so. Never fabricate data.
- Signed everything. Envelopes are Ed25519-signed; peer fingerprints are
mutually pre-pinned. Reaching the bus is not being trusted.
- Reboot-surviving by default. launchd
RunAtLoad+KeepAlive, systemd
Restart=always, NSSM AUTO_START.
- Never hardcode engine paths. Resolve through
NEEDLE_ENGINE_DIR.
Quick start (two machines, one central NATS)
# On each edge: 1) install 2) set env 3) verify
export NATS_URL="tls://nats.example.africa:4222"
export NATS_CREDS="~/.nats/edge1.creds"
export GATEWAY_MESH_ID="reactorpro/edge1"
export NEEDLE_ENGINE_DIR="/opt/neuralos/needle"
bash scripts/bootstrap_edge.sh # macOS/Linux
pwsh -File scripts\bootstrap_edge.ps1 # Windows
bash scripts/doctor.sh # expect all PASS
bash scripts/dispatch.sh reactorpro/edge2 reactorpro/edge2-butler butler.query \
"which customer spent the most?"
Then read references/examples.md for the multi-edge, cross-org and
Africa multi-country patterns.
1---2name: neuralos-a2a-mesh3description: Install, configure, operate and troubleshoot an end-to-end agent-to-agent (A2A) messaging and communication system across multiple, diverse and disparately-networked systems using neuralOS on-device inference plus the ReactorPro gateway mesh, over a central NATS server. Use when deploying, extending, benchmarking, hardening or repairing a neuralOS/Gateway multi-edge mesh — macOS, Linux, Windows, cloud VMs, on-prem servers, edge devices, intermittent or air-gapped networks. Covers requirement gathering (asks when parameters are missing), cross-platform installation and service wiring, signed skillproxy butler lanes with mandatory needle grounding, cross-organisation trust, day-2 operations, upgrade/rollback, and deep connection troubleshooting including NATS/TLS/permissions/leaf-node/fingerprint/engine-selection failures. This is the standard template for neuralOS/Gateway A2A deployments across Africa and beyond.4metadata:5 source: https://skillmd.com/skills/drolu/neuralos-a2a-mesh6---78# neuralOS A2A Mesh — deploy, operate, troubleshoot910An end-to-end **agent-to-agent (A2A) messaging system** built from three11layers that this skill wires together:1213| Layer | Component | What it provides |14|---|---|---|15| **Transport** | NATS / Synapse subjects | request/reply, pub/sub, JetStream durability, leaf nodes across networks |16| **Trust + routing** | `reactorpro-gateway` (v1.7.5+) | Ed25519-signed envelopes, fingerprint pins, `invoke` + `skillproxy` lanes, REST/UI on `:3000` |17| **Intelligence** | neuralOS / needle engine | offline 121M tool-calling model that grounds every butler query to a read-only probe |1819Every remote action is: **question in → engine selects a probe → read-only20execution → small capped digest back over a signed envelope.** There is no21keyword-only fallback in the serving path.2223## The one rule2425**Every requirement is either already given or you must ask for it.** Never26invent a NATS URL, account, credential, fingerprint, service account, path or27port. Run the intake in `references/parameters.md` before installing anything;28if a required value is missing, request it from the operator and wait.2930## Workflow31321. **Intake** — read `references/parameters.md`, collect every REQUIRED33 parameter (central NATS server, per-edge identity, creds, pins, ports,34 service accounts, engine dir, butler skills). Ask for anything missing.352. **Design the topology** — pick from `references/architecture.md`36 (single edge → two-edge → three-edge → multi-country hub-and-spoke with37 leaf nodes). Confirm the shape with the operator.383. **Install per host** — follow `references/install.md` for macOS, Linux and39 Windows (engine, gateway, butler harness, service wiring, verification).404. **Wire trust** — exchange fingerprints out of band, set mutual41 `LIVEAGENT_GATEWAY_MESH_TRUSTED_PEERS`, `-mesh-verify-mode=require`,42 `-mesh-trust-on-first-use=false` on every edge.435. **Stand up a butler** — use `references/butler-harness.md` and44 `scripts/butler_template.py`; mandatory needle grounding, read-only probes,45 honest holes.466. **Verify end to end** — run `scripts/doctor.sh` / `doctor.ps1`, then a47 never-seen-before benchmark from at least two origins48 (`scripts/dispatch.sh`). Do not sign off without it.497. **Operate** — `references/operate.md` (health, upgrades, rollback, reboot50 survival, capacity, key/credential rotation, adding an edge or skill).518. **Troubleshoot** — `references/troubleshooting.md` when anything fails;52 work top-down: transport → trust → gateway → butler → engine → data.5354## References (one hop, load on demand)5556| File | Read when |57|---|---|58| `references/architecture.md` | designing the topology; envelope/subject/trust semantics; leaf nodes and cross-org |59| `references/parameters.md` | **before every install** — the full intake questionnaire + central NATS server parameters |60| `references/install.md` | installing engine/gateway/butler on macOS, Linux or Windows; service wiring |61| `references/butler-harness.md` | writing or extending a butler skill; menu design; skillproxy contract |62| `references/operate.md` | day-2: health, benchmarks, upgrades, rotation, reboot survival, new edges |63| `references/troubleshooting.md` | any failure — connection, TLS, permissions, trust, engine selection, cross-platform |64| `references/examples.md` | simple → complex worked examples end to end, including the Africa multi-country playbook |6566## Scripts6768| Script | Purpose |69|---|---|70| `scripts/doctor.sh` / `doctor.ps1` | full environment + connectivity diagnostic; prints a pass/fail report |71| `scripts/dispatch.sh` / `dispatch.ps1` | call a remote butler through the signed `skillproxy` lane; measures wall time |72| `scripts/butler_template.py` | cross-platform butler harness: ask.py retrieval → needle → read-only probe → capped digest |73| `scripts/bootstrap_edge.sh` / `bootstrap_edge.ps1` | install engine + gateway + butler as a reboot-surviving service |74| `scripts/nats_central.conf` | central cloud NATS server template (TLS, accounts, JetStream, leaf-node acceptor) |75| `scripts/nats_edge.conf` | edge/client-side NATS config + leaf-node remote template |7677Run a script with the platform's shell: `bash scripts/doctor.sh`,78`pwsh -File scripts\doctor.ps1`. Scripts read parameters from environment79variables and say exactly which are missing.8081## Non-negotiable constitution8283- **Mandatory needle grounding.** Every butler query routes through the84 on-device engine. No deterministic keyword fallback in the serving path.85- **Read-only probes.** Buttlers execute only probes from their86 `needle_menu.json`. No writes, no arbitrary shell, no credentials.87- **Honest holes.** Upstream failure ⇒ relay the error verbatim. No probe88 selected ⇒ say so. Never fabricate data.89- **Signed everything.** Envelopes are Ed25519-signed; peer fingerprints are90 mutually pre-pinned. Reaching the bus is not being trusted.91- **Reboot-surviving by default.** launchd `RunAtLoad`+`KeepAlive`, systemd92 `Restart=always`, NSSM `AUTO_START`.93- **Never hardcode engine paths.** Resolve through `NEEDLE_ENGINE_DIR`.9495## Quick start (two machines, one central NATS)9697```bash98# On each edge: 1) install 2) set env 3) verify99export NATS_URL="tls://nats.example.africa:4222"100export NATS_CREDS="~/.nats/edge1.creds"101export GATEWAY_MESH_ID="reactorpro/edge1"102export NEEDLE_ENGINE_DIR="/opt/neuralos/needle"103bash scripts/bootstrap_edge.sh # macOS/Linux104pwsh -File scripts\bootstrap_edge.ps1 # Windows105106bash scripts/doctor.sh # expect all PASS107bash scripts/dispatch.sh reactorpro/edge2 reactorpro/edge2-butler butler.query \108 "which customer spent the most?"109```110111Then read `references/examples.md` for the multi-edge, cross-org and112Africa multi-country patterns.