Device Labels

Labeling helps you to manage your devices at scale. You can use labels to schedule, configure or query subset of the devices

Labels are used to:

  • Filter your devices when searching for a particular group or a single device.

  • During application deployment, as applications can provide a selector with a list of labels and their values.

Labels can be added to devices in several ways:

  • Manually through API/CLI/dashboard.

  • Through a registration token (when device is being provisioned).

  • Automatically by the agent itself, if labels are found in the configuration directory.

Labeling devices

Add labels through dashboard

Labels can be added (or removed) to devices either through the devices table or through the device details page:

Manually editing devices is mostly useful when operating with a relatively small number of devices or when slowly adding them to your project. If you need to label large number of devices, consider using registration token labeling or device self-label functionality.

Add labels through registration token

Registration token labels can be edited in the provisioning page.

Once registration token labels are set, any new devices registering to the system will inherit them. You can modify registration token labels at any time, it will not affect existing devices.

Adding labels to the registration token is useful when booting large number of devices in batches. For example, if you have a token that is embedded in your OS image and 10 000 devices, you can modify the token for

Device self-labeling

Synpse allows devices to apply labels to themselves using a configuration file.

By default synpse looks for a labels configuration in /etc/synpse/labels file. File format is


For example, a device with this file:

$ cat /etc/synpse/labels

You can use provisioning scripts to automatically update the labels file. Any updates to it will automatically get sent to the Synpse controller.


You can filter your devices by using exact match, for example labelKey:labelValue to get all devices that have this specific combination or just by specifying labelKey: to list all devices that have labelKey in the their labels with any value.

Last updated