Install and register a bridge

A bridge is one service on one machine. Install it on a machine that can reach your devices on the local network and can open an outbound HTTPS connection.

Requirements

Linux with systemd, or macOS
amd64 or arm64
administrator rights, for one prompt during installation
an outbound route to api.staging.nodelets.com, and, behind a proxy, a proxy that allows WebSocket connections

There is no Windows build.

Install

curl -fsSL https://staging.nodelets.com/install.sh | sh

The script chooses the build for your system, downloads it with a SHA-256 checksum and stops if the two do not match. It then installs the service with one administrator prompt:

	Linux	macOS
Executable	`/usr/local/bin/nodelets`	`/usr/local/bin/nodelets`
Service	systemd unit `nodelets`	launchd daemon `com.nodelets.bridge`
State directory	`/var/lib/nodelets`	`/Library/Application Support/Nodelets/state`
Control socket	`/run/nodelets/control.sock`	`/Library/Application Support/Nodelets/run/control.sock`
Logs	`journalctl -u nodelets`	`/Library/Logs/Nodelets/bridge.log`

The service runs as its own account, nodelets on Linux and _nodelets on macOS. The installer allows the account that ran it to use the bridge straight away. Other local accounts are refused until the installer is run as them.

Register

nodelets login
nodelets bridge register

nodelets login prints a link and a code. Open the link, check that the code on the Approve CLI access page on https://dashboard.staging.nodelets.com matches, and choose Approve.

nodelets bridge register enrols this machine’s bridge with the signed-in account and prints its bridge ID. Run it as your own account, not with sudo. The bridge makes its own private key, which never leaves the machine, and your sign-in session never enters the service.

If the installer has not run, for example because you downloaded the executable by hand, bridge register installs the service first and asks for administrator approval.

Check

nodelets bridge status

The status shows the service, the cloud connection, the registration, the installed definitions and the Things, with what to run next. A green dot is healthy, yellow is in progress or needs attention, red has failed, and a hollow grey dot is a state the CLI could not observe. Add --json for a document a script can read.

The dashboard’s Bridges page shows the same bridge with its status, when it last connected, the start of its key fingerprint and its Nodelet count.

Control the service

nodelets bridge stop
nodelets bridge start
nodelets bridge restart

Each asks for administrator approval.

Upgrade

Run the installer again. It replaces the executable, keeps the state directory, and prints the build it replaced and the build it installed. The bridge keeps its ID, its key and its Things.

Running the installer as another local account also allows that account to use the bridge. The installer never removes an account it allowed.

Keep the state directory

The state directory holds the bridge’s identity, its keys, its definitions and its Things. It must persist. The bridge changes its key once a day, so a copy of the directory from before the last change holds an old key, and the cloud refuses it. A restored backup, or a container image with the directory baked in, is refused this way within a day. To bring such a bridge back, see Recover a bridge.