Skip to content
Nodelets

Why the bridge dials out

The bridge never listens on the network. It opens one WebSocket connection to the Nodelets API host and keeps it open, and everything the cloud asks of the bridge travels down that connection.

What this keeps closed

Section titled “What this keeps closed”
  • No inbound port. Nothing on the local network has to accept a connection from outside, and no router or firewall rule has to change.
  • A fixed set of calls. The cloud can send the bridge four kinds of request: run an operation (thing.interact), start a subscription (thing.subscribe), stop one (thing.unsubscribe), and cancel a request in flight (request.cancel). An operation names a Nodelet and a capability, and the bridge runs it only if the installed definition binds it. There is no request for a network address, a raw HTTP call or a topic that a definition does not name.
  • Site details stay on site. Base URLs, brokers, topics and headers are held by the bridge. The cloud refers to devices by Nodelet ID only.
  • The equipment stays as it is. The bridge talks to devices with the protocol they already speak. There is no new firmware, vendor gateway or hub. A device must already answer HTTP with JSON, or use an MQTT broker.

The bridge’s own control socket, used by the CLI, is a local Unix socket on the machine, not a network listener.

How the bridge proves who it is

Section titled “How the bridge proves who it is”

The bridge holds a private key that never leaves its state directory. At each connection the cloud sends a challenge naming the key it expects, and the bridge signs it. Registration uses your signed-in session once, through the CLI, and the session never enters the service.

A connected bridge changes its key once a day, at a time the cloud gives it, and keeps its bridge ID. The connection stays open through the change, so subscriptions and commands carry on. An old key is refused, and when the cloud can prove the key was this bridge’s, the refusal appears on the account record. A daily change does not stop someone who copies a key and uses it first, but it turns silent long-term use into a visible lockout: the real bridge is refused, you see why, and recovery restores it.

What it costs

Section titled “What it costs”
  • A route out is required. The bridge has no local API. Without a path to the cloud it does nothing, and devices on that bridge cannot be reached through Nodelets.
  • A proxy must allow WebSockets. A proxy that only passes plain HTTP requests blocks the bridge.
  • Every operation crosses the cloud. A read or a write travels from the client to the cloud, down the bridge’s connection and back. That suits supervision, not control loops or safety functions, which belong on the local controller.
  • One connection per bridge. Commands and live values share it. The bridge keeps a separate queue per device, so one noisy device loses its own oldest values and does not take another’s place, but a command’s reply still travels the same connection. During a long stall a command can reach its device and its caller can still get OUTCOME_UNKNOWN.
  • The cloud sees values. Values and commands pass through the cloud in plaintext.
  • The state directory must persist. Because the key changes daily, a restored backup or a container image with a baked-in state directory holds an old key and is refused.