ReactorPro Gateway — Server Setup
The ReactorPro gateway is a single static Go binary. It serves the ReactorPro web UI, brokers connections from ReactorPro desktop apps, and can join a NATS/Synapse agent mesh so that agents in one organisation reach agents in another. There are no runtime dependencies: no Docker, no Go toolchain, no Node, no shared libraries. One file, one token, one config.
Use this skill to stand it up on a server and keep it running.
Install (one line, every OS — native binaries, offline after install)
PyPI — first choice on all platforms:
pip install synapse-gateway
Platform wheels bundle the synapse-gateway + reactorpro-agentd native
binaries (checksum-verified at build time) and put synapse-gateway /
synapse-agentd commands on PATH. Node.js: npm i -g @hyperspaceng/synapse-gateway.
One-line bootstrappers (macOS/Linux/Windows, download from GitHub Releases +
verify SHA256SUMS):
curl -fsSL https://synapse.hyperspace.ng/install.sh | sh # also: https://synapse.neuralos.ng/install.sh
irm https://synapse.hyperspace.ng/install.ps1 | iex
GitHub release assets keep their historical reactorpro-gateway-<goos>-<goarch>
names; the pip/npm-installed commands are synapse-gateway / synapse-agentd.
Which kind of deployment are you building?
The gateway works with or without a desktop app attached, and the settings differ. Answer this first — it changes what you configure and what you can expect.
| If… | Go to |
|---|---|
| No ReactorPro desktop app will connect — a VPS, jump host, or central node | Gateway only |
| One organisation, one site, desktop apps connecting | Standard site |
| Several of your own sites that should find each other | references/scenarios.md → S3 |
| Another company involved | references/scenarios.md → S4 |
| Some edges are not upgraded yet | references/scenarios.md → S5 (read this — it prevents the most confusing failure) |
| Regulated or hostile-adjacent traffic | references/scenarios.md → S6 |
| A partner organisation with no desktop agents of their own | references/scenarios.md → S7 |
references/scenarios.md carries the full playbooks: what to set, how to verify, and what each
scenario cannot do.
The shape of a deployment
Five things matter, and getting the first three wrong is the usual cause of a gateway that "runs" but does not work:
- A gateway token. The only required setting. Nothing else is mandatory.
- A listen address. Defaults to
:443, which is almost never what you want on a server. Set it explicitly. - A persistent data directory. Holds the SQLite database and the mesh identity. The identity is not reproducible — lose it and the keypair is gone for good.
- A service manager so it survives logout, reboot, and crashes.
- Optionally, the mesh bridge — disabled unless explicitly enabled and pointed at a NATS server.
Quick start
Install with the bundled script — it detects the platform, downloads from GitHub Releases, and verifies the SHA-256 checksum before installing:
scripts/install-gateway.sh # installs to /usr/local/bin (or ~/.local/bin)
scripts/install-gateway.sh --with-systemd # ...and installs + starts a systemd service
Then confirm it is actually healthy, not merely running:
curl -s localhost:3000/healthz # {"ok":true} — no token needed
curl -s -H "Authorization: Bearer $TOKEN" \
localhost:3000/api/mesh/status # agentId + fingerprint
/healthz only proves the process is listening. The authenticated checks are what tell you the
gateway is configured correctly — see Verify the deployment below.
Manual install
Binaries are published per release for five targets. Download the matching one:
| Platform | Asset |
|---|---|
| Linux x86-64 | reactorpro-gateway-linux-amd64 |
| Linux ARM64 | reactorpro-gateway-linux-arm64 |
| macOS Intel | reactorpro-gateway-darwin-amd64 |
| macOS Apple silicon | reactorpro-gateway-darwin-arm64 |
| Windows x86-64 | reactorpro-gateway-windows-amd64.exe |
BASE=https://github.com/DrOlu/ReactorPro/releases/latest/download
curl -fsSLO "$BASE/reactorpro-gateway-linux-amd64"
curl -fsSLO "$BASE/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS # macOS: shasum -a 256 -c
install -m 0755 reactorpro-gateway-linux-amd64 /usr/local/bin/synapse-gateway
Verify the checksum. These are unsigned binaries; the checksum is the only integrity signal you get, and it is worthless if you skip it.
Pin a version by replacing latest/download with download/v1.5.8.
You can also confirm what you are running without downloading anything — GitHub exposes a server-computed digest per asset:
gh api repos/DrOlu/ReactorPro/releases/tags/v1.5.8 --jq '.assets[]|{name,digest}'
Configure
Settings come from command-line flags, environment variables, or both. Flags win over environment variables; for each setting the flag's value is simply initialised from the environment, so passing the flag overrides it.
Two rules of thumb:
- Put the token in the environment, never in the command line. Arguments are visible to every
user on the host via
ps. Use anEnvironmentFile(systemd), a0600file sourced by a launcher (launchd), or the service's environment (Windows). - Quote only what needs quoting. The gateway trims whitespace but does not strip quote
characters from a value — so quotes must not be part of the value. Quotes that are file syntax
are fine: systemd's environment-file parser and a shell
sourceboth remove surrounding quotes before the gateway sees the value, which is how you pass a path containing spaces. The failure mode is quotes that reach the process literally, e.g.docker run -e LIVEAGENT_GATEWAY_TOKEN='"abc"'— the gateway then expects the quotes to be sent by every client, andBearer abcgets a 401.
Minimal configuration:
LIVEAGENT_GATEWAY_TOKEN=$(openssl rand -hex 32) # 256-bit; 32+ chars is sensible
LIVEAGENT_GATEWAY_HTTP_ADDR=:3000
LIVEAGENT_GATEWAY_DATA_DIR=/var/lib/synapse-gateway
The five settings that cover almost every deployment:
| Setting | Flag | Env var | Default |
|---|---|---|---|
| Gateway token | -token |
LIVEAGENT_GATEWAY_TOKEN |
(required) |
| Listen address | -http-addr |
LIVEAGENT_GATEWAY_HTTP_ADDR |
:443, or :$PORT if PORT is set |
| Data directory | — | LIVEAGENT_GATEWAY_DATA_DIR |
user config dir |
| TLS cert / key | -tls-cert / -tls-key |
LIVEAGENT_GATEWAY_TLS_CERT / _KEY |
(off — plain HTTP) |
| Mesh on/off | -mesh-enabled |
LIVEAGENT_GATEWAY_MESH_ENABLED |
false |
Run synapse-gateway --help for the full list. references/configuration.md documents every
flag with its default and when to change it.
Choosing a listen address
127.0.0.1:3000— behind a reverse proxy or only for local apps. Preferred for anything internet-facing; the proxy terminates TLS.:3000— reachable from the LAN. Required when desktop apps on other machines connect directly, and when running in a container.:443(the default) — only correct if the gateway itself terminates TLS.
The gateway speaks plain HTTP unless you give it -tls-cert and -tls-key. Terminating TLS at
nginx/Caddy/Cloudflare in front of a loopback bind is simpler to operate and keeps certificate
renewal out of the gateway.
The data directory
LIVEAGENT_GATEWAY_DATA_DIR is the base for two files:
gateway.db— SQLite database of per-agent tokens. Auto-created. Safe to back up.mesh/reactorpro-identity.json— the mesh identity. Not reproducible. See below.
Without it the gateway falls back to the OS user-config directory (~/.config/liveagent on
Linux, ~/Library/Application Support/liveagent on macOS, %AppData%\liveagent on Windows). Set
it explicitly on a server so the location is obvious and service-independent.
Back up mesh/reactorpro-identity.json before your first upgrade. The file holds an Ed25519
keypair and a fingerprint computed over the agent id and the public key. Edit the id inside it
and the file refuses to load; point the config at a different id and startup fails with "the
agent id is part of the fingerprint and cannot be reassigned". Every outbound envelope is signed
and carries that fingerprint, and the manifest advertises it so peers can pin this gateway.
So losing the identity file is not silent: a new keypair is minted under the same agent id, and any peer that already pinned the old fingerprint will refuse this gateway as an identity mismatch. Restore from backup, or accept the new identity and tell your peers.
Access control
The gateway has exactly one authentication mechanism:
Authorization: Bearer <gateway token>
That header form is required — a bare token, ?token=, or a custom header is rejected with 401.
Everything under /api/ is gated by it. Two exceptions:
GET /healthz— unauthenticated, returns{"ok":true}. Safe for load balancers and orchestrator probes.GET /plus/assets/*— the embedded web UI, unauthenticated (the UI asks for the token itself).
Give each desktop agent its own credential rather than sharing the gateway token:
POST /api/agents/{id}/token. Per-agent tokens let you revoke one machine without rotating every
client. references/api.md has the request shapes.
Run it as a service
Pick the section for the platform. Full unit files, hardening options, and Docker notes are in
references/service-managers.md.
Linux — systemd
# /etc/systemd/system/synapse-gateway.service
[Unit]
Description=ReactorPro Gateway
After=network-online.target
Wants=network-online.target
[Service]
User=reactorpro
EnvironmentFile=/etc/synapse-gateway.env
ExecStart=/usr/local/bin/synapse-gateway --http-addr=127.0.0.1:3000
Restart=always
RestartSec=5
StateDirectory=synapse-gateway
[Install]
WantedBy=multi-user.target
install -d -m 0750 -o reactorpro -g reactorpro /var/lib/synapse-gateway
printf 'LIVEAGENT_GATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" \
> /etc/synapse-gateway.env
chmod 0600 /etc/synapse-gateway.env
# add: LIVEAGENT_GATEWAY_DATA_DIR=/var/lib/synapse-gateway
systemctl daemon-reload && systemctl enable --now synapse-gateway
The environment file must be readable by the service user — 0600 owned by root works because
systemd reads it as root before dropping privileges, but 0640 root:reactorpro is clearer if you
ever start the binary by hand.
macOS — launchd
~/Library/LaunchAgents/ng.reactorpro.gateway.plist starts at login; put the same file in
/Library/LaunchDaemons/ to start at boot (needs sudo and a UserName). RunAtLoad starts
it, KeepAlive restarts it after a crash. Keep the token in a 0600 file the launcher reads at
start time rather than inline in the plist. A working pair of files is in
references/service-managers.md, and the templates ship in scripts/.
Windows
The binary is not a Windows service — sc.exe create will fail. Either use a wrapper (NSSM,
WinSW) or a Task Scheduler entry with "Run whether user is logged on or not" and a trigger of "At
startup". Set the token as a machine environment variable (setx /M) so it is not in the task's
arguments.
Docker
An image is published as ghcr.io/drolu/liveagent-gateway. That name is a legacy internal
identifier kept deliberately; it is the ReactorPro gateway. Mount the data directory as a volume
so the identity survives container replacement, and remember to publish the port (-p 3000:3000)
with --http-addr=:3000.
Connecting desktop apps
In each ReactorPro desktop app, open Settings → Remote:
| Field | Value |
|---|---|
| Gateway URL | http://<host> — include the scheme |
| Port | the --http-addr port, e.g. 3000 |
| Access Token | the gateway token, or a per-agent token |
Include http://. A bare host is normalised to https:// by the client, which then fails against
a plain-HTTP gateway with a TLS error that looks nothing like a config mistake.
Once connected, the agent appears in the gateway's local directory — and that directory is what gets published to the mesh, so peers can see what sits behind your edge without being told.
No desktop agent? (gateway only)
A gateway with no ReactorPro desktop app attached is a legitimate deployment, not a half-finished one. It serves the web UI and API, holds a mesh identity, appears in the directory, and answers the read-only skills.
It cannot serve invoke with nothing attached, because there is no local agent to route
work to — a peer asking for a task gets 3002 AGENT_UNAVAILABLE. Its published local_agents
list will be empty, which is exactly how a peer can tell there is nothing behind it.
Unless you attach reactorpro-agentd — the headless worker. It signs into the gateway exactly the way a desktop app does, appears in the same directory, and turns the server into an execution node with no desktop app anywhere in sight. See the next section.
Typical uses: a VPS or jump host, a central registry/directory node for a group of organisations, a visibility node at a partner, or a site that will have its desktop app added later — adding one requires no change to any peer.
The headless worker — reactorpro-agentd
A single static binary that signs into a gateway over the same /ws/v2/agent WebSocket the
desktop uses and serves remote chat turns with real tool use, several at once. To the
gateway it is just another attached agent — a row in the local directory, addressed by target
or capability, behind the same gates, tasks, streaming and webhooks. No gateway or mesh
configuration changes to adopt it. The companion detail — every flag, service files,
verification — is in references/agentd.md.
When you want it
- A server/VPS should execute work, not merely relay it — and no human will sit at a desktop.
- Parallel turns: the desktop runs one turn at a time behind its user; the agentd runs
-concurrencyat once (default 4) with a polite queue. - The mesh's task lifecycle (async tasks, streaming, webhooks, retry, input-required) should have an unattended worker to feed.
Install
BASE=https://github.com/DrOlu/ReactorPro/releases/latest/download
curl -fsSLO "$BASE/reactorpro-agentd-linux-amd64" # per platform; see below
curl -fsSLO "$BASE/SHA256SUMS"
sha256sum -c --ignore-missing SHA256SUMS # macOS: shasum -a 256 -c
install -m 0755 reactorpro-agentd-linux-amd64 /usr/local/bin/reactorpro-agentd
Assets: reactorpro-agentd-{linux-amd64,linux-arm64,darwin-amd64,darwin-arm64,windows-amd64.exe}.
Pure-Go, genuinely static — no runtime dependencies. scripts/install-agentd.sh does the
download-verify-install for the current platform.
Issue its credential
The agentd authenticates like a desktop: the gateway token, or better, its own per-agent
token (revocable independently). The agent id must be the canonical form agent-<uuidv4 lowercase> — anything else is refused:
AGENT_ID="agent-$(uuidgen | tr 'A-Z' 'a-z')"
curl -s -X POST -H "Authorization: Bearer $GATEWAY_TOKEN" \
http://127.0.0.1:3000/api/agents/$AGENT_ID/token # -> {"token":"agt_…"}
curl -s -X PATCH -H "Authorization: Bearer $GATEWAY_TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"ReactorPro Agentd (server 1)"}' http://127.0.0.1:3000/api/agents/$AGENT_ID
The friendly name is what peers see in the published directory — set it.
Configure and run
LIVEAGENT_AGENTD_PROVIDER_KEY=sk-… \
reactorpro-agentd \
-gateway ws://127.0.0.1:3000/ws/v2/agent \
-agent-id "$AGENT_ID" -token "$AGENT_TOKEN" \
-name "ReactorPro Agentd (server 1)" \
-provider-url https://api.openai.com/v1 \
-provider-model gpt-5 \
-workdir /srv/agentd-work \
-skills-dir /opt/agent-skills \
-concurrency 4
The essential settings:
| Setting | Flag | Env twin | Notes |
|---|---|---|---|
| Gateway link | -gateway |
LIVEAGENT_AGENTD_GATEWAY |
ws:// or wss:// agent endpoint |
| Identity | -agent-id |
LIVEAGENT_AGENTD_ID |
agent-<uuidv4> — its directory address |
| Credential | -token |
LIVEAGENT_AGENTD_TOKEN |
gateway or per-agent (agt_…) token |
| Provider | -provider-url / -provider-key / -provider-model |
LIVEAGENT_AGENTD_PROVIDER_* |
any OpenAI-compatible /v1 endpoint; the worker holds this key, not the gateway |
| Sandbox | -workdir |
LIVEAGENT_AGENTD_WORKDIR |
every file tool + shell cwd confined here (symlink-safe) |
| Skills | -skills-dir |
LIVEAGENT_AGENTD_SKILLS_DIR |
library of SKILL.md collections, exposed read-only |
| Parallelism | -concurrency |
LIVEAGENT_AGENTD_CONCURRENCY |
default 4; extra commands queue |
| Reach | -shell / -fetch |
LIVEAGENT_AGENTD_SHELL / _FETCH |
toggle the two wide-blast tools |
Run it under systemd/launchd like the gateway (a full unit file is in references/agentd.md).
Reconnects with bounded backoff; a dropped link cancels local runs and the gateway fails them at
their budget.
What it serves — and what it does not
Served: invoke tasks (mesh dispatch and async tasks alike), streaming chunks, webhooks, retry,
input-required — the full task contract; a curated tool set (read_file, write_file,
list_dir, run_command, fetch_url) plus read-only skill tools (read_skill,
read_skill_file) when -skills-dir is set.
Not served: desktop-surface requests it does not implement are answered instantly with a typed
501 refusal (it is an executor, not a desktop), and history_list returns an honest empty list —
the agentd keeps no conversation history. Chatting with it through the web UI works on the live
conversation view; persisted history does not exist.
Verify
# 1. It signed in (agentd log): "agentd signed into the gateway"
# 2. The gateway sees it — the agents list on /api/status includes the id
curl -s -H "Authorization: Bearer $GATEWAY_TOKEN" http://127.0.0.1:3000/api/status
# 3. Peers can discover it (within one heartbeat of the gateway): describe shows
# local_agents carrying the worker by name
# 4. A real turn end to end:
curl -s -X POST -H "Authorization: Bearer $GATEWAY_TOKEN" -H 'Content-Type: application/json' \
-d '{"target":"<your-edge-id>","skill":"invoke","timeoutMs":180000,
"input":{"target":"'"$AGENT_ID"'","operation":"task",
"arguments":{"prompt":"Say OK and nothing else."}}}' \
http://127.0.0.1:3000/api/mesh/dispatch
The standard site
One organisation, one site, desktop apps connecting to one gateway:
LIVEAGENT_GATEWAY_MESH_ENABLED=true
LIVEAGENT_GATEWAY_MESH_URL=nats://127.0.0.1:4222
LIVEAGENT_GATEWAY_MESH_AGENT_ID=acme/lagos/edge-1
LIVEAGENT_GATEWAY_MESH_CAPABILITIES=agent,reactorpro
Mesh authentication accepts exactly one of: a token, user + password, or a credentials file (in
that order of precedence — -mesh-creds-file for NKey/JWT wins over both). Enabling the mesh
without a URL is refused at startup, and setting a user without a password is refused too — the
bridge refuses to half-start. A connection failure, by contrast, is not fatal: the gateway
keeps serving and records the reason on /api/mesh/status. So "the service is running" never
proves the mesh works.
Give every edge a unique id — do this before you need it
LIVEAGENT_GATEWAY_MESH_AGENT_ID is an address, not a label:
- it forms the subject peers send to —
mesh.agent.<id>.inbox; - it is hashed into the identity fingerprint.
On first start the gateway mints an identity file, and from then on the id is permanent. Configuring a different one later is a hard startup failure ("the agent id is part of the fingerprint and cannot be reassigned"), not a warning. Changing it means moving the identity file aside to mint a new one — which changes your fingerprint and breaks every peer that pinned it.
Use <org>/<site>/<edge>. Every edge needs a different id: two edges sharing one discard each
other as "self", so the mesh looks empty while every service reports healthy. The gateway detects
this and logs a collision warning — and if you are still on the shared legacy default
(drolu/reactorpro) it warns loudly at startup, because an edge on that id cannot federate.
Left unset, the id defaults to reactorpro/<sanitised-hostname>. Fine for one site; set it
explicitly before federating.
What the mesh can do
Eight skills are served (v1.5.19+): read-only (ping, describe, status), the caller-scoped task set (task.get, task.cancel, task.retry, task.input), and the gated invoke. describe returns the full manifest including this edge's agent directory — desktops and headless workers, refreshed every heartbeat since v1.5.24.
| Skill | Answers | Risk |
|---|---|---|
ping |
"Are you there?" | read-only |
describe |
The full manifest, including this edge's agent directory | read-only |
status |
Identity, uptime, traffic counters. Deliberately narrow — never reveals local agents or tokens | read-only |
invoke |
"Ask one of your agents to do this" | does work — gated |
invoke: letting a peer reach an agent behind your edge
A verified peer asks one of your desktop agents to run a task, by naming an agent or a capability:
{"target": "agent-1111", "operation": "task", "arguments": {"prompt": "..."}}
{"capability": "task", "operation": "task", "arguments": {"prompt": "..."}}
Give one or the other — both is refused, and neither is defaulted, because an edge should not
guess which laptop to run work on. timeout_ms may only tighten the deadline, never extend it.
Note the two different capability lists: -mesh-capabilities is what this edge advertises so
peers can find a site that can do something; the capability field in an invoke request matches
what the attached desktop agents advertise, so the receiving edge can pick an agent.
How a remote task actually executes
The desktop has no separate "run a task" interface — its model, tools and agent loop all live in its own runtime. So the edge does not invent a second way in: it submits an ordinary chat command to the desktop over the same WebSocket the browser uses, the desktop runs a real tool-using turn, and the result returns through the existing reliable chat channel. One path, so it cannot drift from normal chat behaviour.
If the caller's deadline passes, the edge tells the desktop to cancel, so an abandoned request does not keep running and spending the local user's provider quota. That cancellation is best-effort: if the desktop is unreachable at that moment, it cannot be delivered.
The gates — and the one that matters most
| Setting | Default | Meaning |
|---|---|---|
-mesh-allow-remote-invoke |
on | Is the capability offered at all? |
-mesh-require-verified-invoke |
on | The floor. Refuse work from a caller whose identity was not verified |
-mesh-invoke-operations |
task |
Exact allowlist. Empty exposes none, never all |
-mesh-invoke-timeout |
3m |
How long one synchronous remote job may run (a caller may only narrow it; hours-long work is the async task API) |
-mesh-skills-enabled |
on | false serves nothing at all, invocation included |
Read this before you turn the floor off. The default verify mode is prefer, which
accepts unsigned envelopes. So invocation without the floor would be reachable by anything
able to publish to the NATS subject — anonymous remote code execution on a desktop machine. With
it on, "allowed to invoke" means "allowed for an authenticated peer". Keep it on across
organisation boundaries. Startup validation refuses the contradictory combination (invoke on +
require-verified + verify-mode=off), because there every invocation would be refused.
Finding each other: discovery and the registry
Each edge publishes its manifest into a JetStream key-value bucket, and discovery reads it — deterministic, unlike the older broadcast window that could silently miss a slow peer.
LIVEAGENT_GATEWAY_MESH_REGISTRY=auto # default
LIVEAGENT_GATEWAY_MESH_REGISTRY_BUCKET=mesh_registry
LIVEAGENT_GATEWAY_MESH_REGISTRY_TTL=1m30s
auto(default) uses both the registry and the broadcast, merged.jetstreamis registry-only and fails startup without JetStream — for a closed fleet where you know every peer publishes to the bucket.broadcastnever touches JetStream.
If any edge in your fleet is not upgraded, use
auto. A registry-only setting makes you blind to every peer that publishes nothing to the bucket — older builds, or a different implementation. It fails silently, because the registry read succeeds (it returns at least your own entry), so the fallback never runs and the mesh looks healthy while empty. Seereferences/scenarios.md→ S5.
Registry entries are data, not identity. An entry read from the bucket can never make a peer trusted; trust comes only from a verified signature.
Entries also expire (TTL), so a crashed edge stops being advertised. That is intended, but it means the directory is a view of now, not a durable record.
references/mesh.md has the full model: identity, subjects, error codes, and reputation.
Verify the deployment
Work down this list — each step depends on the one before it:
TOKEN=$(grep -oP '(?<=LIVEAGENT_GATEWAY_TOKEN=).*' /etc/synapse-gateway.env)
# 1. Process is listening (no auth)
curl -s localhost:3000/healthz
# 2. Token is accepted. A 401 here means the token is wrong, was rotated, or has
# quote characters inside the value — see references/troubleshooting.md.
curl -s -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer $TOKEN" localhost:3000/api/status
# 3. The web UI is served
curl -s localhost:3000/ | grep -o '<title>.*</title>'
# 4. Mesh — only meaningful if you enabled it
curl -s -H "Authorization: Bearer $TOKEN" localhost:3000/api/mesh/status
# 5. Peers are reachable
curl -s -H "Authorization: Bearer $TOKEN" localhost:3000/api/mesh/agents
# 6. Record the fingerprint. It must not change across an upgrade.
curl -s -H "Authorization: Bearer $TOKEN" localhost:3000/api/mesh/status \
| grep -o '"fingerprint":"[^"]*"'
Expected results:
/healthz→{"ok":true}/api/status→200/api/mesh/status→connected: true, anagentId, and afingerprintof the formsha256:<16 hex chars>/api/mesh/agents→ a list of peers (empty is correct if you have not federated yet)
/api/mesh/agents takes about two seconds, and that is correct. With -mesh-registry=auto,
discovery still waits out the broadcast window because peers may answer individually as well as
through the registry. Do not point a 1-second HTTP timeout at it and conclude the mesh is broken;
allow at least 3 seconds.
If /api/mesh/status reports connected: false, read its lastError field — it carries the
reason. references/troubleshooting.md covers the common ones.
Upgrading
The upgrade is: replace the binary, keep the data directory, restart.
systemctl stop synapse-gateway
install -m 0755 reactorpro-gateway-linux-amd64 /usr/local/bin/synapse-gateway
systemctl start synapse-gateway
curl -s -H "Authorization: Bearer $TOKEN" localhost:3000/api/mesh/status
Confirm the fingerprint is unchanged afterwards. If it changed, you pointed the new process at a different data directory and it minted a fresh identity — fix the path and restore the backup before anything else, because peers have already seen the new one.
After upgrading a mesh, check /api/mesh/agents and confirm the peer count did not drop. A count
that falls to zero right after an upgrade is a discovery regression, not an outage — see
references/scenarios.md → S5.
Troubleshooting index
| Symptom | Likely cause |
|---|---|
| Exits immediately, "gateway token is required" | LIVEAGENT_GATEWAY_TOKEN empty or unset |
| Service runs, every client gets 401 | Quotes round the token in the env file, or a trailing newline |
| Reachable on the host, not from outside | Bound to 127.0.0.1; or host/cloud firewall |
connected: false, lastError mentions authorization |
Wrong NATS credentials; check for quotes in the NATS config |
connected: false, lastError mentions connect |
NATS unreachable at LIVEAGENT_GATEWAY_MESH_URL |
| Zero peers, but everything reports healthy | Duplicate agent id; peers not subscribed; or an unhealthy registry bucket. Work down references/troubleshooting.md — this is the most common mesh fault and the most misleading |
| Peer count dropped after an upgrade | The v1.5.1 auto-mode discovery regression; upgrade, or set -mesh-registry=broadcast as a workaround |
Invocation refused 4003 GOVERNANCE_DENIED |
The floor working: caller unsigned, or fingerprint not pinned |
| Peer count drops to zero after an edge restarts | Its registry entry expired (TTL); it repopulates on the next heartbeat |
/api/mesh/agents times out in a client |
Client timeout under ~3s; discovery waits out the broadcast window |
| TLS handshake error from the desktop app | Gateway URL lacks http:// |
| WebSocket failures through a proxy | Proxy not configured for upgrade on /ws/v2* |
| A log file growing very fast | A crash-looping service, usually bad credentials. Truncate it (: > file) — a plain delete does not free space while the writer holds the file open |
references/troubleshooting.md covers each with diagnosis commands.
Knowing it is working
The counters on /api/status (under protocol_usage) tell you more than any single check:
mesh_inbound_totalrising, withmesh_verify_failed_totalandmesh_trust_mismatch_totalat zero — peers are genuinely talking to you.mesh_invoke_denied_totalrising whilemesh_invoke_totalstays flat — your policy is holding a peer off, which is exactly what you want to see when you expect it.mesh_outbound_totalexists but is not currently incremented; do not read its zero as meaning anything.
Reference files
Read these when you need the detail — they are not loaded until you open them.
references/scenarios.md— the scenario playbooks: gateway-only, one site, multi-site, federated, mixed fleet, closed fleet, and a partner with no desktops.references/configuration.md— every flag and environment variable, with defaults and guidance on when a value needs changing.references/mesh.md— the NATS/Synapse mesh: identity model, authentication, served skills, remote invocation and its gates, discovery and the registry, subjects, error codes.references/service-managers.md— complete systemd, launchd, Windows, and Docker setups, including reverse-proxy configuration.references/api.md— HTTP endpoints, authentication, request/response shapes, and agent token issuance.references/agentd.md— the headless worker: every flag and env twin, per-agent token issuance, service files, the skills library, verification, upgrade and limits.references/troubleshooting.md— symptom → diagnosis → fix, with commands.
For questions about the ReactorPro desktop application itself (features, skills, MCP servers), use
the reactorpro-doc skill instead — this one is about the server.
Recent changes you must know about (v1.5.4 → v1.5.35)
The durable mailbox (v1.5.4, opt-in). -mesh-mailbox buffers skill
invocations for an absent agent in JetStream (mesh.agent.*.mailbox, stream
MESH_AGENT_MAILBOX) and delivers them when it returns. At-least-once: skills
reached this way must be idempotent. Send with POST /api/mesh/mailbox (202).
Never stream the inbox subject, and never reuse a name you do not own (v1.5.5).
A JetStream stream over mesh.agent.*.inbox breaks request/reply outright: the
server answers the publish, so callers receive a PubAck instead of the
response, and a push consumer's msg.reply is the ack subject, so the peer
cannot reply at all. Durability belongs on .mailbox. If a stream with the
configured name already exists, the edge adopts it only when it genuinely
captures this agent's mailbox subject, otherwise it refuses with an actionable
message — it never rewrites a stream it did not create. A mailbox failure is
non-fatal and shows as mailbox.running=false + error on /api/mesh/status.
Dispatch is honest now (v1.5.6–v1.5.8). It ignores ack-shaped messages,
refuses to treat a non-envelope as a successful reply, and names the likely
cause on timeout. Requests also carry a top-level text (from
input.text/message/prompt) and a signed payload.reply_to with a _REPLY
prefix, which is what the Synapse cli/agentspan bridges require. Cross-fleet
dispatch with a text prompt is a real agent turn — allow 120s+.
See references/mesh.md § "The durable mailbox and the inbox hazard".
The async task lifecycle (v1.5.12–v1.5.19). The mesh send ceiling rose to 30 minutes
(timeoutMs up to 1800000), and invoke gained "async": true — a task object with states
(queued → working → (input-required) → completed | failed | canceled | rejected), a
caller-minted id as the idempotency key, state events on mesh.event.task.<id>, opt-in chunk
streaming, signed webhook push on completion, one-call retry, and an interactive
pause-and-ask protocol (allowInput + [[INPUT_REQUIRED: …]]) that resumes in the same
conversation. Tasks are served by any attached agent — desktop or headless worker.
The headless worker, reactorpro-agentd (v1.5.20–v1.5.22). A second executor ships in the
box: a static binary that attaches as an agent and runs turns in parallel. First release, then
the skills library (-skills-dir, read-only read_skill/read_skill_file tools), then the
browser-surface fix — desktop-surface requests it does not implement are answered instantly
with a typed 501 instead of hanging the web UI, and history_list returns an honest empty list.
Discovery publishes the directory now (v1.5.23–v1.5.24). Two stacked bugs had silently
kept every edge's published local_agents empty since v1.5.5: registration ran once at boot
(never refreshed), and the async registry probe was discarded whenever it won the start-up
race. Both fixed — the heartbeat now rebuilds the manifest from the live directory and
re-registers, so peers see your attached agents (desktop and headless alike) within one
heartbeat, and the registry KV entry can no longer outlive its TTL. If an upgraded peer still
reports an empty directory, its edge simply needs one heartbeat (~30s).
The bug-sweep release (v1.5.25). Three concurrency/platform/discovery fixes: the agentd
enforces one run per conversation atomically (a cancel while queued settles the run as
cancelled without a provider call); run_command works on Windows (cmd /c there, sh -c
elsewhere); and a cleanly stopped edge can no longer be resurrected in the discovery registry
by a straggling heartbeat tick — the entry's removal is final.
The synchronous-invoke deadline is 3 minutes (v1.5.26). The edge's own patience for one
remote invoke was 60s, which killed real agent turns that were still working (4001 + a
cancel of a healthy run). A caller can still narrow it per invoke with timeout_ms; hours-long
work belongs to the async task API.
Concurrent inbox and the real invoke deadline (v1.5.32–v1.5.33). The sweep that
followed the UI work found two more, both live-verified: the inbox subscription ran its
handler on nats.go's single delivery goroutine, so one minutes-long invoke queued every
other mesh message to the edge (pings, cancels, other peers' invokes) behind it — it is
now a bounded worker pool (16 workers, 256-deep queue), pinned by a regression test that
fails with the pool forced to 1. And the synchronous-invoke deadline was still 60 seconds
despite v1.5.26: the gateway-level -mesh-invoke-timeout flag carried its own 60s literal
default that silently overrode the raised mesh-package constant — the flag default is now
mesh.DefaultInvokeTimeout (3 minutes), so the two cannot disagree. Operators tune it
with the flag or LIVEAGENT_GATEWAY_MESH_INVOKE_TIMEOUT.
Transcript rendering and retention (v1.5.30–v1.5.31). Two follow-ups found by
browser-reproducing the transcript view: the worker's user entries now carry the
attachments: [] array the webui's snapshot validation requires (without it every
projection the worker committed was silently discarded — prompts rendered, answers
never did), and a finished headless conversation retains its final projection on the
gateway's stream until the stream is reaped, so the history view lives the stream's
full ~30-minute idle life instead of the event log's 10-minute clock. Verified in the
real browser: the worker's answers now render in the chat view, including replies to
messages typed in the management UI.
The headless sidebar fix (v1.5.29). The webui scopes an agent's sidebar to "none" — an
empty list that never asks the gateway — when the settings' execution mode is not "text" and
no workspace project is active, and a headless worker landed there every time (its
settings_get used to fail against the worker's typed 501). The gateway now serves
settings_get for headless workers with the plain-text execution mode (and history_workdirs
as an honest empty list), so the sidebar lists the worker's conversations like the desktop's.
Before this, they were reachable only via Search Conversations.
Headless workers have history and memory (v1.5.27–v1.5.28). The agentd declares the
agentd capability in its hello, and the gateway keys two conveniences on it: the management
UI's history arms for a headless worker are answered by the gateway from its conversation
store (recent activity — ~30-min retention, cleared by a gateway restart), and a synchronous
invoke that passes conversation_id continues that conversation — the desktop continues
its own thread, while a headless worker is rehydrated with its prior turns (newest 16 / 24 KiB).
Replies carry conversation_id so the caller can hold the session. The served transcript
merges all of a conversation's runs, titled from the original prompt.
Streamed provider rounds and bounded proxy silence (v1.5.35). During a slow-provider
window (2026-09-17) both LLM clients treated a slow upstream as a dead one: the agentd sent
non-streaming completions under a 120s total client timeout (a stalled round died with
"context deadline exceeded … awaiting headers" and lost the turn), and the desktop's proxy
client had no timeout at all (the same stall hung until the connection dropped and surfaced
as 502 Failed to forward the proxy request upstream). The agentd now streams
(stream: true, SSE deltas assembled — including fragmented tool calls), and
-request-timeout is an idle timeout: the longest the provider may stay silent between
bytes, before or after headers, with a 15-minute per-round hard cap; a stalled round fails
fast with provider stream stalled: no data from the provider for …. Slow-but-alive
providers that keep sending bytes or SSE keepalives are never cut, and a provider answering
a streamed request with plain JSON is still served. The desktop's proxy and system-proxy
clients gained connect_timeout(15s) + read_timeout(300s) (idle-between-bytes) with no
total timeout by design — streamed answers are only ever cut by upstream silence.
Agentd-free edges — gateway + butler harnesses (v1.7.5 skillproxy pattern)
The recommended minimal edge no longer includes an agentd. A gateway (the only network-facing co
…(truncated)