Reset device data

Start fresh with new identities

This walkthrough covers the "nuke and start clean" workflow for a device when its registries and on-disk state have drifted out of sync with each other. By the end you'll have a freshly initialized device with no inherited sentients, nodes, hives, or audit data.

When to do this

The startup state machine + registry self-heal cover most drift cases automatically. Reach for this guide only when:

  • The sentient picker keeps mislabeling Shadow vs Secured even after mounting each sentient.
  • You're debugging an issue that's confounded by inherited state.
  • You changed the on-disk data format and need a clean slate to verify the new layout.

Routine UX issues (logout-then-login, switching identities, etc.) do not need a wipe.

1. Locate the data folder

Each app stores its data in its own folder under your user data location. Where your data lives gives the folder of each app on each platform. The steps below use the Hub, so <hub data folder> stands for the data folder of the Hub.

You can also override the location at launch with --basedir /path/to/wherever if you want to keep multiple device profiles side by side.

2. Back up first

The folder holds your sentient hives — the encrypted vaults that own your identities. Nuking destroys them. Back up first if there's any chance you'll want to recover later:

cp -r "<hub data folder>" \
      "<hub data folder>.backup-$(date +%F)"

3. Shut down the app

The store files are open while the app is running. Quit normally — do not kill -9 unless you know the SaveState cascade has already drained (the lanyard's progress dot stops spinning).

4. Wipe the folder(s)

rm -rf "<hub data folder>"

Optional but recommended for a truly clean state: wipe the matching settings folder too. App settings live separately, under ~/.config/ on Linux, and persist some flags that aren't strictly UI preferences — most notably the pairing-skipped boolean. If you leave them in place a brand-new device will inherit "pairing was skipped" from your previous identity and the unboxing wizard's pairing chip will light amber before you've done anything.

rm -rf "<hub settings folder>"

If you do want to keep window positions, debug toggles, etc., you can edit the settings JSON in place and clear only the identity-scoped keys (look for pairing-skipped, unboxing-*).

5. Relaunch + walk through unboxing

When you start the app again the StartupStateMachine sees the empty folder and walks you through:

  1. Welcome / sentient choice — Create new, Import from phrase, or Import from another device.
  2. Sentient creation — your first sentient lands as a shadow (no user-set passphrase yet, auto-mounts with the public default).
  3. Security upgrade prompt — sets your real passphrase. This is the call that writes device_owner.json AND flips the registry's isShadow=false. Both stores stay in sync.
  4. Node creation — agent/remote/hub identity inside the sentient.

After unboxing the sentient picker will correctly read Secured; the lanyard chip will match. No self-heal needed because the data is born pristine.

What changed in the persistence layer

If you arrived here from a debugging session, the canonical sources of truth for "is this sentient secured?" are now centralised in libhive/hive/SentientSecurity.hpp. The picker, lanyard tooltip and the security-upgrade gate all route through sentientSecurityFor(), which checks three signals in priority order:

  1. device_owner.json next to the hive's storePath (strongest — disk truth).
  2. SentientEntry.passphrase — any non-empty, non-default value reads as user-set.
  3. SentientEntry.isShadow registry flag (weakest — legacy fallback).

The security cases of the testSentientRegistry test suite lock this contract in place; a regression on any of the three signals fails the build.

Future on-disk format changes

When we change the data layout in a future release, the right pattern is:

  1. Bump the format version in the affected store's serialised header.
  2. Add a one-shot migration that converts on-load. Keep the legacy path readable for at least one release cycle so users can roll back.
  3. Cover the migration with a test that loads a fixture in the old format and asserts the migrated shape — test/testSentientRegistry is the model.
  4. Document the migration in content/doc/internal/changelog.md.

Nuking should be a user choice during a major release, never a forced upgrade step. If a clean reinstall is the simplest path for the user to recover from a bug, that's a defect in the migration path — file it as such.

In this section