Architecture

HALO separates concerns into a small set of compiled Rust binaries, each statically linked and deployable as a single file. There are no runtime dependencies on the control path. A flashable OS image boots directly into a working node.

Components

Five binaries make up a HALO deployment. Each is cross-compiled to aarch64-unknown-linux-musl and run under systemd.

The control plane is modular. main.rs is router setup only; handler logic lives across more than a dozen modules under src/api/ — flows, nodes, system, mesh, camera, external systems, speedtest, and others. Binaries are version-stamped with the git commit hash and build timestamp, exposed at /health and via --version.

Gateway and node roles

A HALO network has exactly one gateway. The gateway runs the full control plane — API, database, flow engine, and topology computation — on a single ARM board drawing under 5 W, with no cloud dependency for core operation. It is also the mesh exit point: the path to upstream connectivity and the internet.

Every other device is a node. Nodes run halo-mesh and halo-agent, peer into the mesh, and report telemetry to the gateway over the encrypted overlay. The service dependency chain is halo-mesh → gateway-api + halo-agent; mesh is the root dependency on every device.

Brain and neuron model

HALO models a deployment as a brain composed of neurons.

• Brain — the HALO platform as a whole.
• Neuron — a logical unit within the brain. Each neuron has four standard components.

Neuron components follow the naming convention brain-<component>-<neuron>, for example brain-sensor-n01.

These are logical roles, not fixed physical devices. A single board may host one or several neuron components. Never assume a one-to-one mapping. Reason from brain to neuron to component role to physical device.

Canonical device model

Every physical device maps to a single canonical identity. Interfaces, sensors, attached endpoints, roles, and telemetry sources are modeled as children of that identity, not as independent objects. A node that moves from Ethernet to mesh to overlay remains one node. This prevents inventory duplication across transport changes and keeps topology computation clean.

The terminology is precise and consistent across the API, CLI, and UI:

• Node — a device running HALO software.
• Gateway — the single controller node; control-plane services and the HALO exit point.
• HALO network — one ethrx deployment boundary, containing one or more meshes and nodes.
• Mesh — an authenticated RF domain defined by an SSID/channel/PSK profile, for example ETHRX0001-8A.
• Data provider — a non-gateway node that supplies telemetry. Presented as Sensors in the UI.
• Data consumer — a non-HALO endpoint attached locally to a node. Presented as Clients in the UI.

Self-healing by design

The mesh manager continuously monitors link state, peer count, radio process health, and routing table integrity. On failure it applies graduated recovery: re-initiate peer discovery, then restart the radio stack, then reload the kernel driver. Background maintenance loops scan for lost peers every 30 seconds and re-establish links automatically. The system is validated against single-node reboot, gateway-only reboot, and simultaneous full-network reboot. In each case the mesh re-peers, re-acquires addresses, and restores encrypted reachability without operator intervention.

Where to go next

• See how the radio and tunnel layers fit together in networking.
• Read how telemetry and automation use this model in HALO Flows.