RELAY-EDGE

The upstream brain for Zyvor Relay.

Site topology, three companion simulators, and stamped events — publishing into Relay's Accept → Notify → Ack → Act → Verify loop, without real IoT hardware.

Apache-2.0 Go 1.27+

Get the highlights.

• 471
  Firewater sensor points
• 772
  Fleet devices, 18 classes
• 243
  Remote-edge assets
• 24
  Publish paths: direct or via relay-pubsub

• ❓

  FAQ

  Licensing, support, scope, and production-readiness questions.

  →
• 🏭

  Simulators

  Farm, firewater, remote-edge, and fleet, each with a web UI and REST API.

  →
• 🤝

  Integration guide

  How relay-edge, Relay, and Zynera fit together, plus the one-command stack scripts.

  →
• 🚀

  Getting started

  Run relay-edge locally in a couple of minutes.

  →
• ✅

  Test results

  Lab verification — what we tested, how, and the outcomes.

  →

relay-edge is a synthetic IoT/farm site and event simulator for Zyvor Relay. It stamps realistic site topology — seasons, sites, zones, devices, and contacts — onto four built-in simulators (farm, firewater, remote-edge, fleet) and publishes stamped events into Relay, either directly or via relay-pubsub, giving Relay's Accept → Notify → Ack → Act → Verify loop realistic traffic to develop and demo against, without real IoT hardware.

For the full project overview, architecture diagram, and quickstart, see the README on GitHub.

Start here

• FAQ — licensing, support, scope, and production-readiness questions
• Simulators — farm, firewater, remote-edge, and fleet, each with a web UI and REST API
• Integration guide — how relay-edge, Relay, and Zynera fit together, plus the one-command stack scripts
• Zynera — how the optional sibling Zynera control plane relates to relay-edge
• Getting started — run relay-edge locally in a couple of minutes

Documentation map

I want to…	Go to
Run locally in 2 minutes	Getting started
Understand the architecture	Concepts
relay-edge + Zynera + Relay together	Integration guide · Stack without Zynera (diagrams)
Simulate full stack (Zynera optional)	./scripts/e2e-stack.sh / ./scripts/e2e-direct-stack.sh — see Integration
Lab test results (what we ran)	Test results
Publish into Relay (direct or via pubsub)	Working with Relay
Deploy to a host or Kubernetes	Deployment
Production / user site	Production runbook
Lab hosts (any may be remote)	Deployment § Lab reference · Test results
Cut a release / pull GHCR image	Deployment § CI and releases · Releases
Drive events through relay-pubsub → Relay	Event matrix
Explore firewater / remote-edge / fleet simulators	Simulators
Look up HTTP routes	API reference
Environment variables	Configuration
Lab Act wiring (TLS / targets)	lab-wire-relay-act.sh · Test results
Contribute / report security	Contributing · Security
SPDX headers on source	License headers
Use as a customer / operator	User guide

The stack

  relay-edge          relay-pubsub           Zyvor Relay              Zynera (optional)
  ───────────         ──────────────         ───────────              ─────────────────
  domain + sims  →    Pub/Sub REST     →     Accept                   Decision Records
  simulators          topic = type           Notify → Ack → Act        (human gate)
  /ui control rooms   self-signed TLS        Verify

relay-edge never replaces Relay — it feeds Relay with stamped, policy-ready events. When Zynera is co-located, Relay may require Zynera freeze/attest before Act — relay-edge does not call Zynera; see Zynera.

What's inside this repo

Piece	Description
Farm domain	Sites, zones, devices, contacts, seasons — JSON on disk
Stamping	Every publish enriched with season/site/zone/recipients/probe
Firewater	47-point industrial fire-water plant + edge AI/comms
Remote edge	24 assets: Starlink, Galleon, UAV, vision, yard IoT
Fleet	77 devices across 18 edge classes in one catalog
Web UIs	/ui home + self-test lab · /ui/firewater.html · remote-edge · fleet · docs
CI / release	GitHub Actions: vet + unit + 4 smokes; tag-gated binaries + ghcr.io/zyvorai/relay-edge

Scripts cheat sheet

./scripts/smoke.sh                 # farm lifecycle
./scripts/smoke-firewater.sh       # industrial plant
./scripts/smoke-remote-edge.sh     # remote-edge scenarios
./scripts/smoke-fleet.sh           # fleet catalog + scenarios
make smoke-all                     # all four smokes (EDGE=…)
./scripts/e2e-events-matrix.sh     # all 4 families → Relay
./scripts/e2e-direct-relay.sh      # direct Relay (no pubsub, expanded scenarios)
./scripts/e2e-direct-stack.sh      # direct: probe + scenario matrix
./scripts/stack-probe.sh           # health: edge + pubsub + Relay (+ Zynera)
./scripts/stack-probe.sh --direct  # health: edge + Relay only
./scripts/e2e-stack.sh             # no Zynera: probe + event matrix
./scripts/e2e-zynera-stack.sh      # matrix + Zynera path when ZYNERA_* set
./scripts/lab-wire-relay-act.sh HOST  # wire Relay Act → pubsub (TLS insecure)
./scripts/deploy-remote.sh HOST    # systemd (or nohup fallback)
./deploy/scripts/deploy-k8s-remote.sh HOST   # k8s stack (+ sibling relay-pubsub)

CI: PR/push → vet, go test, local smokes (incl. fleet). Release: push v* or Actions → Release (binaries + GHCR).

Latest lab verification: Test results (2026-08-29 — 212 + 175 PASS).

Related projects

• relay-pubsub — Google Pub/Sub gateway → Relay
• relay — control plane
• Zynera — AI/K8s at edge sites; Decision Records with Relay
• Contributing · Security · Releases

1. Firewater models a full NFPA-style plant across 47 sensor points. See Simulators overview. ↩
2. Fleet is the master edge catalog: 77 devices across 18 edge classes. See Simulators overview. ↩
3. Remote edge tracks 24 assets across a distributed site NOC. See Simulators overview. ↩
4. Publish via relay-pubsub (production) or directly to Relay. See Working with Relay. ↩