Labels

A label identifies a group of devices within a project. A device can have any number of labels, such as production, canary, or maintenance. Labels have stable IDs beginning with d_label_; renaming a label preserves its assignments and selectors. Names are unique within a project, ignoring case and surrounding whitespace. Colors and descriptions are optional. Choose any RGB background color with the color picker or enter a six-digit hex value, such as #1741a3. Label text uses black or white, whichever has higher contrast.

Labels are separate from properties. Properties store named JSON values such as configuration, inventory, and reported state. Labels represent membership. Writing a property does not add or remove a label. Selectors can combine label conditions with property predicates.

Manage Project Labels

Open Project Settings → Labels to manage the project’s catalog. Create Label and each label’s Edit button open a slide-out for its name, color, and description. Saving changes preserves the label’s identity and device assignments. Delete removes the label from the catalog and every device after confirmation.

Add and Remove Device Labels

On a device page, labels appear alongside status and version information. Use the pen icon beside Labels to open the editing dialog. Assigned labels appear as pills with an × control to remove them. Search for additional labels and choose from the autocomplete suggestions, which exclude labels already selected. Save Labels applies the changes; Cancel discards them. Removing a membership leaves the label in the project catalog.

In the device list, select rows and choose Edit Labels beside the selection count above the table to apply membership changes in bulk. Clear Selection deselects the rows without changing their labels. Adding an existing membership or removing an absent one has no effect; unrelated labels are preserved.

Catalog changes require project device-management permission. Membership changes require device-settings permission for every selected device. Device credentials cannot change memberships. Catalog changes and actual membership changes appear in the audit log.

Select Devices

Use the label dropdown beside search and status to select one or more labels. Options and selected labels appear as pills using each label’s color. Devices match when they have any selected label. Clearing the selection removes that restriction.

Expand Advanced in the filter row for all, any, and none conditions, combined with AND. The Has any labels selection is shared with the dropdown. Advanced starts collapsed; a count beside its title indicates active all/none conditions.

Filters combine with device search and status and are preserved in the URL.

Use Labels in Operations

To target an operation by label, open Operations, choose the project, and click New Operation. The same label conditions are available in the operation editor, where a target preview shows matching devices and property-evaluation errors. The preview reflects current membership; actual targets are resolved when the operation starts.

Snapshot operations select devices once. Dynamic operations enroll newly matching devices on later enrollment passes. Removing or deleting a label never cancels work already assigned to a device. A maintenance label only excludes future enrollment when the selector explicitly excludes it.

Deleting a label removes it from every device, even when an operation references it. The operation retains the label’s ID: conditions requiring that label stop matching, while conditions excluding it match devices without it. Recreating a label with the same name creates a new identity.

API Example

The Python SDK uses the same selector for device queries and fleet operations:

from nexigon_hub_sdk.api_types.devices import (
    CreateDeviceLabelAction,
    DeviceId,
    DeviceLabelSelector,
    UpdateDeviceLabelsAction,
)
from nexigon_hub_sdk.api_types.projects import ProjectId, QueryProjectDevicesAction
from nexigon_hub_sdk.api_types.fleet import FleetOperationTargetSelector

project_id = ProjectId("p_...")
device_id = DeviceId("d_...")

canary = client.execute(
    CreateDeviceLabelAction(project_id=project_id, name="canary", color="#1741a3")
)
client.execute(
    UpdateDeviceLabelsAction(
        project_id=project_id,
        device_ids=[device_id],
        add=[canary.label_id],
        remove=[],
    )
)

selector = FleetOperationTargetSelector(
    predicates=[],
    labels=DeviceLabelSelector(all=[canary.label_id]),
)
matches = client.execute(
    QueryProjectDevicesAction(project_id=project_id, selector=selector)
)

Pass selector unchanged to CreateFleetOperationAction to use the same targeting conditions. QueryProjectDevicesOutput.selection_errors reports devices whose property predicates could not be evaluated, separately from matching devices.

Omitting a label condition imposes no restriction. Empty all and none lists also impose no restriction; an explicitly empty any list matches no devices. The UI omits a condition when its selection is cleared. Label IDs without assignments in the project, including deleted labels, are absent from every device in that project.