Edge / User Admin

Appearance

Rename ​

A Device's hostName is the mutable human-readable label — "Richard's Laptop", "office-mac", "garage-pi." This page covers what is supported today and the target rename UI.

What "rename" changes vs doesn't ​

hostName is mutable and human-only. Renaming it does not change:

  • installId — the durable install identity.
  • hostId — the bond identity.
  • deviceSlug — the address-safe management projection key.
  • routeKey / publicNamespace / spaceId / authorityRoot — the Space identity.

So the URL https://hivecast.ai/<spacePath>/edge/ stays the same. The Device's place in system.devices stays the same. Only the human label changes.

Today's rename procedure ​

Status: in-place rename is target state. The current path is "re-pair with new --device-name" or "edit storage."

Re-pair with new name (canonical workaround) ​

bash
# 1. Disconnect the Device (revoke current Host Link)
hivecast logout --revoke-cloud-link --home <host-home>

# 2. Re-pair with the new label
hivecast login --device --cloud https://hivecast.ai \
  --route-key <spacePath> \
  --device-name "New Friendly Name" \
  --home <host-home>

This is disruptive — the Device drops offline briefly during the swap.

Edit credential file (sneaky workaround) ​

bash
# 1. Stop the local Host
hivecast stop --home <host-home>

# 2. Edit the link record's hostName field
sudo jq '.hostName = "New Friendly Name"' \
  <host-home>/credentials/hivecast-link.json > /tmp/link.json
sudo mv /tmp/link.json <host-home>/credentials/hivecast-link.json

# 3. Restart
hivecast start --home <host-home>

This updates the local hostName only. The platform's record stays old until next heartbeat (which propagates the new label, target). In practice today, the platform's record is updated only at create time — re-pair is needed to update the platform's hostName.

Target: in-place rename ​

A target auth.hostLink.rename op (or system.devices.devices.rename) would:

  1. Verify the calling principal owns the link.
  2. Update hostName on the Host Link record.
  3. Not touch deviceSlug (which is collision-resolved at create time).
  4. Audit-log.

CLI: hivecast device rename <hostLinkId> "<new-name>" or via the HiveCast Devices page.

Why deviceSlug doesn't track hostName ​

Per HIVECAST-DEVICE-ENROLLMENT-SPEC.md:

deviceSlug is allocated once by system-auth from hostName, collision-resolved under principal + Space. It is not regenerated when hostName changes.

If deviceSlug tracked hostName, every rename would change every URL referencing the Device. Since deviceSlug is stable, URL references survive renames.

Why no deviceName field ​

deviceName is forbidden in new contracts (per CLAUDE.md and the spec). It was ambiguous between "the slug" and "the label." Use hostName for the mutable label, deviceSlug for the address-safe key.

The CLI keeps --device-name as user-facing language (operators write CLI scripts in human terms), but the field that actually gets written is hostName.

Rename multiple Devices ​

If you have several Devices and want to rename all of them — say, to apply a naming scheme — the only path today is to re-pair each. Bulk rename is target.

What labels are valid ​

hostName is a free-text string. Constraints:

  • Reasonable length (UI may truncate).
  • No control characters.
  • Avoid characters that break shell quoting (since CLI flags carry the value).
  • UTF-8 acceptable.

There is no enforced uniqueness across a principal's Devices. Two Devices both named "laptop" are allowed but confusing — use distinct labels.

See also ​

Source: projects/matrix-3/packages/system-auth/src/host-auth.ts:97 for the schema. No rename op today.