Device lifecycle & organization assignment¶

All lifecycle actions are on Admin → Devices in the portal, apart from Move to environment, which is on the device page.

Lifecycle states¶

prepared ─┐
          ├→ assigned → retired
holding ──┘

State	Meaning
prepared	A logical device created ahead of its hardware: id, name, optional organization and model, no box and no token. Its config can be built now.
holding	A box that has enrolled but belongs to no organization. Registered and reporting, not in service.
assigned	Belongs to an organization and is in service.
retired	A unit whose hardware and identity were folded into another device by Connect or Replace. The row is kept for provenance.

The Devices list filters by All, Prepared, Holding, Assigned, Retired and Revoked. No action sets revoked, so that filter is empty.

Logical device vs physical box

A device's id, name, organization, config and history belong to the logical device. The box behind it can change without the device changing identity, which is what Create device, Connect, Replace and Clone rely on. See Device Lifecycle for the model.

The Admin area¶

Tab	Purpose
Devices	The inventory and every lifecycle action below
Enrollment	Mint and revoke bootstrap tokens and device codes
Organizations	The organizations devices are assigned to
Relays	The relay fleet
Profiles	Per-organization defaults for service profiles

Organization actions¶

Action	What it does	Who
Assign	Put a `holding` device into an organization; it becomes `assigned`.	Platform admin, Support admin
Move	Reassign an `assigned` device to a different organization.	Platform admin, Support admin
Return to holding	Detach an `assigned` device from its organization; it goes back to `holding`.	Platform admin
Delete	Remove the device record.	Platform admin
Console	Open a remote root console (online devices).	See console

Assigning or moving changes only ownership, never the running configuration. From the moment a device is assigned, only members of its organization (and platform staff) can read or change it.

Bulk actions¶

Select several rows to assign, return to holding or delete them together. The result reports partial success ({ok} done, {fail} failed), so a run that half-worked is visible.

Staging and swapping hardware¶

These act on the logical device rather than on the box. All four are platform admin only.

Create device¶

Stage a device before its hardware exists. Give it a Name, optionally an Organization and a Hardware model. With a model, the device offers that model's ports at once, so its whole config can be built ahead. It appears as prepared.

Connect¶

Fold a unit from the holding zone into an existing device, typically a prepared one. Pick the unit, then the Device to connect it to.

The unit's identity token and hardware details move onto the chosen device, which becomes assigned. Its id, name, organization and config stay.
The unit's own row becomes retired.
If the chosen device has a staged config that was never applied, it is promoted and the box pulls and applies it on its first connection. No reflash.
The box adopts the new identity by itself: it restarts on a nudge from Nexus, and otherwise switches on its next reconnect.

Replace hardware¶

Swap the box behind a device for one that has enrolled into the holding zone. The device keeps its id, config, history and organization; only the hardware changes. Replace and Connect are the same operation, and both record a Hardware replaced event in History.

The device being replaced must be offline

Taking over a device overwrites the token its current box uses, and that box is locked out for good. Nexus therefore refuses to connect or replace into a device that is still online ("take it offline first"). Power off or unplug the old box, wait until the portal shows it offline, then replace.

The source unit may be in holding or already assigned (assigning a fresh box before replacing a dead one is allowed). A prepared or retired row cannot be a source: there is no hardware behind it.

Clone¶

Create a new prepared device seeded with a copy of an existing device's latest config, saved as a draft so it is reviewed before it is ever applied. The clone gets its own id and identity, and hardware later through Connect. Use it to roll out a site that looks like an existing one.

Changing environment is different

Assign, Move and Return to holding move a device between organizations within one environment. Moving to another environment (dev, staging, production) re-enrolls it; see Move a device between environments.