Migrate Identity over LAN

Move a sentient identity from one device to another using both devices live on the network — no need to write down or type the 12-word recovery phrase. The receiving device ends up with the same sentient ID, same identicon, same trust relationships.

Tip

If only one device is reachable, use the recovery phrase flow instead. This how-to is for the easier case where both devices are on the same LAN and already paired.

When to use this

Prerequisites

1. Both devices paired. If they aren't, go through Pair via LAN Discovery first. The peer must already be in the address book of each device with TRUST level.
2. Both devices on the same LAN. The migration uses the existing peer connection — no extra network setup.
3. Network discovery enabled on both devices. Fresh installations start with all discovery channels OFF; turn on Network in the channel selector on either device (the migration screens also have inline channel toggles, so you can flip it from there if needed).
4. Source device has a real sentient identity. Shadow / placeholder identities can't be migrated.

Steps

On the source device (the one with the identity you want to copy)

1. ☰ Menu → Sentient → Export identity
2. Pick Transfer over network
3. Wait for the confirmation screen. Your six-digit code appears at the top (salmon color, 📤 indicator).

On the destination device

1. ☰ Menu → Sentient → Import sentient
2. Pick Receive from device
3. Wait for the confirmation screen. Your six-digit code appears at the bottom (baby blue color, 📥 indicator).

Verify the codes

Within about two seconds, both devices show both codes — the source device's code (salmon, top) and the destination device's code (blue, bottom). The two screens should be visually identical apart from the "Your code" / "Their code" labels.

Look at both screens side by side. If the numbers match position-for-position, you have the right peer.

Confirm on both sides

1. Click Codes match on both devices. Order doesn't matter.
2. The source device transfers the recovery phrase and identity material to the destination.
3. The destination device installs the sentient and shows the same identicon as the source.

What's happening under the hood

1. Both devices broadcast a small announce blob to each other carrying their confirmation code. The receiving side displays it.
2. When both users click Codes match, the source device sends the destination its BIP39 phrase (in the encrypted session — never on disk in cleartext).
3. The destination device derives the same Ed25519 keypair from the phrase and installs it as its active sentient.
4. The destination acks the source. Both screens close. The destination now shows the same identicon and trust relationships.

The whole transfer typically completes in under a second once you click confirm on both sides. The activity has a 5-minute timeout to protect against half-completed migrations.

After the migration

You now have two devices with the same sentient identity. This is intentional — both can act on behalf of the same sentient. You can keep them in sync (operate one, the other reflects), use one as a hot backup, or shut down the source.

Trust relationships transfer too: any peer that trusted the source automatically trusts the destination (same sentient).

If you want to remove the source device's copy after migration, do it explicitly — there's no automatic wipe.

Troubleshooting

Codes never appear

• The two devices aren't actually paired. Open ☰ Menu → Pairing → Contacts and confirm the other device is listed with TRUST level.
• Both devices are on the same side. The source must pick Export identity; the destination must pick Import sentient. If both pick Export (or both Import), the announce protocol drops the blobs because each side expects the opposite role.
• LAN discovery is off. Check the channel toggle on the migration screen — Network should be on.

Codes don't match

• You may be looking at the wrong peer (a third paired device announcing concurrently). Cancel on both and try again, ideally with no other paired devices in migration mode.
• Tampering: if codes don't match and you weren't expecting another peer, abort. The migration only protects against MITM if you actually compare codes — never click "Codes match" without verifying.

"Cancelled by peer"

The other device backed out (closed the migration screen or clicked Cancel) before the transfer completed. Restart the flow on both devices.

Transfer says complete but the destination shows a different identicon

Open an issue. The identicon is a deterministic function of the sentient ID; if it differs, something went wrong in the keypair derivation. The destination should refuse the install rather than mismatching, so this shouldn't happen in practice.

Compared to the recovery phrase flow

Network migration is the recommended path when both ends are available. The phrase flow is the disaster-recovery option.