Migrating an Identity

Move a Sentient identity from one device to another so the same cryptographic identity (and its contact trust state on the receiving device's network) becomes usable on the new machine.

When to use this

• You've replaced a laptop or workstation and want your existing Sentient on the new one
• You're setting up a second device (a dedicated agent, a travel laptop, a backup machine) under the same human identity
• You're recovering after a device loss by restoring from your BIP39 phrase

For the conceptual background — what a Sentient identity actually is and how it's stored — see Sentient Identity.

What "migration" moves — and what it doesn't

Migration moves the cryptographic identity of a Sentient:

• The Ed25519 keypair that derives your SID
• Your display name (since spec follow-up §B-20 lands — see the carry-forward note below)
• The BIP39 recovery phrase (for further migrations and recovery)

Migration does not move:

• Contacts, pairings, or trust state — these are per-device. Re-pairing the new device with your peers is expected.
• Per-Node configuration (the robot personalities you've created) — Node identities belong to the device that birthed them; the new device gets its own Nodes under the same Sentient.
• OPAL audit history, courier blob spool, batch queue state — these are per-device runtime state.

This is by design. A Sentient is who you are; the per-device state is what you've done there. The receiving device starts fresh with the same identity.

Prerequisites

• Both devices have OctoMY™ installed and at least a Shadow Sentient (Sentient A is the source, Sentient B is the receiving device).
• Both devices are reachable from each other on a LAN, or you have the BIP39 phrase from Sentient A written down for the offline-recovery path.
• On the receiving device: enough space for a new sentient hive (a few hundred MB initially, growing with usage).

Step 1: Trigger the migration on the source device

From the Sentient Lobby on the source device:

1. Click the sentient chip in the Lanyard (top-right of every window) to open SentientLobbyActivity.
2. Pick Import / Export — this is the entry to the migration toolset.
3. Choose Export. You'll see a screen with a one-time verification code and an identicon preview of the Sentient being exported.

Verify the identicon matches the identity you actually mean to migrate (especially relevant if you have multiple Sentients on this device).

Step 2: Receive on the new device

On the receiving device:

1. Open the Sentient Lobby → Import / Export → Import.
2. The activity discovers the source device on the LAN (or you can scan the verification code shown on the source).
3. Enter the verification code from Step 1. This authenticates the handshake — both sides confirm they're talking to the device they expect.
4. The migration protocol runs: the source signs an attestation of its identity, the receiver verifies, and the payload (keypair + phrase + display name) is transmitted over the pre-agreed pairing channel.

Argon2id derivation runs on the receiving device — expect a few hundred milliseconds of CPU while the new hive is provisioned.

Step 3: A new sentient hive is created — not overwritten

This is the key architectural change introduced by §SP-10. The imported Sentient lands as a new sentient hive on the receiving device, named SID-<imported-sid-hex> (typed-hive taxonomy — see Hive).

The receiving device's previously-active Sentient is not touched. Pre-spec behaviour would overwrite the active vault; post-spec the imported identity is a peer to whatever's already there.

You can verify by visiting Active Mounts — the just-imported hive appears as another Sentient row alongside the existing one(s), each carrying its owning sentient's identicon.

Step 4: Switch to the imported identity (when you're ready)

After import succeeds, the imported Sentient appears in SentientSelectionActivity alongside any existing Sentients. To activate it:

• From the lanyard: click the sentient chip → Sentient Lobby → Switch sentient → pick the imported Sentient from the list.
• From OPAL: ask OPAL to switch to it by display name.

If the imported Sentient is Full (password-protected — which it almost always is for a real migration), you'll be prompted for the passphrase. This is the same passphrase you set on the source device — migration carries it across so the encryption boundary stays uniform.

Once you confirm, Identity Switching runs its full six-phase cascade and you land on the imported Sentient's home activity.

Step 5: Re-establish trust with your peers

Migration moves identity, not contacts. On the receiving device, your contact list under the imported Sentient is empty. To resume working with the same peers:

• Re-run pairing for each peer you want trust with. They'll see your import as a new peer-card under the same SID — depending on their UI, this may surface as "first contact" or "this peer has appeared on a new device."
• For automated peers (agents you own that already trust your SID), they'll verify the new connection cryptographically using the same keys — trust transfers automatically once the new device proves it owns the SID.

Recovery path: import from BIP39 phrase only

If the source device is unavailable (lost, broken, never coming back), you can still recover the Sentient using just the 12-word BIP39 phrase you wrote down at first boot or after the Shadow → Full upgrade.

On the receiving device:

1. Sentient Lobby → Import / Export → Import from recovery phrase (the variant that doesn't require a source device).
2. Enter the 12 words.
3. The Ed25519 keypair is re-derived; the receiver creates a fresh SID-<derived-sid-hex> hive and lands the identity in it.

This produces the same on-disk result as Step 3 — a new sentient hive sitting alongside whatever was already there.

When you get the "duplicate identity" error

If the receiving device already has a sentient hive named SID-<incoming-sid-hex> — e.g. you're trying to import a Sentient that you imported earlier — the migration aborts with:

This identity already exists on this device.

This is §SP-10a's collision policy. Migration carries only the SID, not the data — overwriting would discard whatever local pairings the existing hive holds without bringing any compensating state across. The two outcomes the design considered:

• Abort with message (what the app does). Forces the user to consciously delete the existing hive first if they really want a clean re-import.
• Merge. Out of scope — there's no sensible "merge two contact lists" UX, and silent merge would surprise users.

If you genuinely want to re-import: from the Hive Lobby, unmount and delete the existing SID-<incoming-sid-hex> hive (which destroys the local pairings under it), then re-run the import.

Troubleshooting

The verification code expires. Codes are short-lived (60 seconds) to limit replay risk. Re-export from the source device.

Source device isn't discovered on the LAN. Both devices must be on the same broadcast domain. VPNs that split-tunnel can break discovery; disable for the duration of the import.

Import succeeds but switching to the imported Sentient prompts for an unfamiliar passphrase. The migration carried the source's passphrase. If you don't remember it, recover via the BIP39 phrase + reset on the new device.

"This identity already exists on this device." See the duplicate-identity section above. The aborted import didn't write anything new.

Switch-now prompt missing. In the current build, the receiving device doesn't yet pop an inline "Switch to this identity now?" prompt after import — that's a small follow-up (Phase 11b enabled it, but the migration UI hook isn't wired yet). For now, the imported Sentient appears in Sentient Selection and you can switch via the lanyard at your leisure.

What's still being built

Related