Core concepts at a glance

How NervesHub is organised: organizations, products, devices, firmware, deployment groups, and releases, and how they fit together.

Written By Josh Kalderimis

Last updated About 2 months ago

NervesHub has a small set of building blocks. Once these click, the rest of the platform follows.

Organization
└── Product
    ├── Devices          (your hardware in the field)
    ├── Firmware         (signed .fw images you publish)
    └── Deployment groups
        └── Releases     (which firmware a group of devices runs)

The hierarchy

Concept	What it is
Organization	The top-level tenant. Owns products, users, signing keys, and CAs. Fleets in different orgs are fully isolated.
Product	A group of devices running the same application. Devices, firmware, deployments, archives, and scripts belong to a product.
Device	A single unit in the field, identified by a unique identifier (usually a serial number).
Firmware	A signed `.fw` image built from your Nerves project, identified by a UUID.
Deployment group	A rule that targets devices (by version and tags) and controls how firmware rolls out to them.
Release	The specific firmware a deployment group is currently shipping.

How an update flows

You build and sign firmware and publish it to a product.
You point a deployment group at that firmware as its release.
Devices matching the group's conditions (version + tags) are offered the update.
The device downloads it, verifies the signature, applies it, and reboots.

Tags are the glue: you label devices with tags, and deployment groups target those tags. That's how you roll a release out to "all field-test units" or "only eu + cellular devices" without touching individual devices.

Two connections, not one

A NervesHub server has two separate endpoints:

A web endpoint for people (the web UI and HTTP API).
A device endpoint for hardware (the long-lived websocket devices connect to).

On NervesCloud these are manage.nervescloud.com and devices.nervescloud.com. When you configure a device, host is the device endpoint.

Where to go next

To learn about	Read
Connecting a device end to end	Quickstart
How devices prove who they are	Device authentication & mTLS
Rolling out safely	Deployment groups & releases
Every term in one place	Terminology