---
created: 2026-08-02T15:30:00.000Z
title: Add a "name your node" step to onboarding (sets the real hostname)
area: ui
severity: major
files:
  - neode-ui/src/views/OnboardingName.vue (to create — match the existing onboarding step design)
  - neode-ui/src/router/index.ts (:26-76 — the onboarding child routes, in flow order)
  - neode-ui/src/composables/useOnboarding.ts (step persistence / resume)
  - neode-ui/src/views/settings/AccountInfoSection.vue (the existing post-onboarding rename UI — reuse its validation)
  - core/archipelago/src/api/rpc/system/handlers.rs (:462 hostnamectl, :58 + :765 regenerate_tls_cert — backend already exists, no change expected)
---

## Problem

Dorian (2026-08-02): wants a step in the onboarding flow to name your node — in the same
design language as the existing steps — which changes the actual hostname.

Today naming only exists **after** onboarding, in `settings/AccountInfoSection.vue`. A fresh
node keeps its install-time default until the user goes looking for the setting.

## What already exists (no backend work expected)

`server.set-name` (`dispatcher.rs:459` → `handle_server_set_name`) already:
- runs `sudo hostnamectl set-hostname <name>` (`system/handlers.rs:462`)
- regenerates the self-signed TLS cert with a SAN covering `<name>`, `<name>.local`,
  `localhost`, `127.0.0.1` (`:58` → `regenerate_tls_cert`, `:765`)
- reloads nginx

Current onboarding order (`router/index.ts:26-76`): Intro → Options → Path → SeedGenerate →
SeedVerify / SeedRestore → Did → Identity → Backup → Verify → Done.

## The hazard that decides the design

**Renaming mid-flow can disconnect the user before their seed is backed up.**

The browser is connected to the node over its current hostname and current TLS cert. `set-name`
changes both: the mDNS `.local` name moves, and the cert is reissued. A user onboarding at
`https://archipelago.local` who renames to `mynode` can lose the session **in the middle of
onboarding** — potentially between seed generation and seed verification, which is the worst
possible moment to drop someone.

That makes step placement a design decision, not an implementation detail. Roughly:

1. **Last, just before Done** — everything security-critical (seed shown, verified, backed up)
   is already complete, so a dropped connection costs nothing but a reload. Safest.
2. **First, before anything else** — the rename happens while there is nothing to lose, but the
   user is asked to name a node before they have any context for what it is, and they may still
   be mid-redirect when the cert changes.
3. **Defer the apply** — collect the name early for good UX, call `set-name` only at the end.
   Best of both, at the cost of holding state across steps.

Option 3 or 1 is almost certainly right. This needs deciding explicitly rather than by
whichever screen the code lands on.

## Also needs deciding / checking

- **Validation + slugification.** Hostnames are RFC-1123: lowercase alphanumerics and hyphens,
  ≤63 chars, no leading/trailing hyphen. A user will type `Dorian's Node`. Decide whether to
  slugify silently, show the slug live ("will be reachable at `dorians-node.local`"), or reject.
  Reuse whatever `AccountInfoSection.vue` already does rather than inventing a second rule.
- **Does the rename propagate everywhere it should?** The Reticulum daemon takes a
  `--display-name`, and mesh/FIPS surfaces show node names. Confirm whether `set-name` updates
  those or whether the node keeps its old name on the mesh until restart.
- **Reconnection UX.** If the cert/hostname change does drop the session, the step should say so
  in advance and tell the user where to come back to — not fail silently into a dead tab.
- **Skippable?** A node with no name is fine; forcing a decision at first run is friction. Decide
  whether the step has a "keep the default" path.

## Solution

Own scope — a quick task or a small plan, not a freehand edit, because of the disconnect hazard
above. Sequence it **after** the in-flight `regenerate_tls_cert` atomicity fix lands (that fix
makes the rename path write the key to a staging file and validate before swapping, instead of
truncating the live key in place if openssl fails partway — renaming is exactly the path it
protects).