obsidian-livesync/docs/setup_p2p.md

# Set up peer-to-peer synchronisation

This guide establishes a peer-to-peer synchronisation set, generates the second-device Setup URI on the working first device, and verifies synchronisation in both directions with explicit peer approval.

Peer-to-peer synchronisation has no central copy of the Vault. At least one device containing the required data must be online when another device fetches it. A Nostr-compatible signalling relay helps devices discover each other, while the Vault data travels through the peer connection.

Before starting:

- back up both Vaults;
- prepare a signalling relay reachable by both devices;
- ensure the networks permit a WebRTC connection, or review the [P2P troubleshooting guidance](./tips/p2p-sync-tips.md);
- disable every other synchronisation service for these Vaults; and
- keep both devices awake and Obsidian open during the initial transfer.

## Generate the bootstrap Setup URI

Run the public generator from a trusted terminal. Supply your own relay for a controlled self-hosted setup:

```sh
export remote_type=p2p
export p2p_relays=wss://relay.example.com
export p2p_room_id=<A PRIVATE ROOM ID> # Optional; generated when omitted
export p2p_passphrase=<A PRIVATE P2P PASSPHRASE> # Optional; generated when omitted
export passphrase=<A STRONG VAULT ENCRYPTION PASSPHRASE>
export uri_passphrase=<A SEPARATE SETUP URI PASSPHRASE>
deno run --minimum-dependency-age=0 --allow-env https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/setup/generate_setup_uri.ts
```

The generated Setup URI contains the encrypted room, relay, and Vault settings. It deliberately omits the device-specific peer name. Store the URI and its passphrase separately.

## Set up the first device

1. Install and enable Self-hosted LiveSync in the intended Vault.
2. Open onboarding from the `Welcome to Self-hosted LiveSync` Notice.
3. Select `I am setting this up for the first time`, then choose the recommended Setup URI method.
4. Paste the bootstrap Setup URI, enter its passphrase, and select `Test Settings and Continue`.

    ![P2P Setup URI on the first device](../images/p2p-setup/guide-p2p-setup-first-setup-uri.png)

5. Complete the first-device initialisation and final confirmation. This initialises the local LiveSync database; P2P has no central remote database to erase.

    ![P2P local initialisation on the first device](../images/p2p-setup/guide-p2p-setup-first-initialise.png)

    ![P2P local database confirmation on the first device](../images/p2p-setup/guide-p2p-setup-first-rebuild-confirmation.png)

6. Keep optional features disabled until ordinary note synchronisation works.
7. Open `Self-hosted LiveSync: Open P2P Replicator` from the command palette. Select `Open connection` if signalling is disconnected.

    ![First P2P device connected to the signalling relay](../images/p2p-setup/guide-p2p-setup-first-device-connected.png)

8. Create an ordinary test note and wait for the local LiveSync progress indicators to clear.

## Generate the second-device Setup URI

On the working first device:

1. Run `Self-hosted LiveSync: Copy settings as a new Setup URI` from the command palette.
2. Enter a new Setup URI passphrase.

    ![Masked passphrase for the additional-device P2P Setup URI](../images/p2p-setup/guide-p2p-setup-copy-setup-uri-passphrase.png)

3. Copy the resulting URI.

    ![P2P Setup URI generated by the working first device](../images/p2p-setup/guide-p2p-setup-copy-setup-uri-result.png)

Keep the first device online. Store the new URI and its passphrase separately.

## Add the second device

1. Install and enable Self-hosted LiveSync in a new or separately backed-up Vault.
2. Open onboarding, select `I am adding a device to an existing synchronisation setup`, and choose the recommended Setup URI method.
3. Enter the Setup URI generated by the first device and its passphrase.

    ![First-device P2P Setup URI entered on the second device](../images/p2p-setup/guide-p2p-setup-second-setup-uri.png)

4. Select `Restart and Fetch Data`.

    ![P2P Fetch confirmation on the second device](../images/p2p-setup/guide-p2p-setup-second-fetch.png)

5. For a new or empty Vault, choose `Overwrite all with remote files`, then `Keep local files even if not on remote`. Review the [Fast Setup guide](./tips/fast-setup.md) before using a Vault which contains local work.

    ![P2P retrieval method](../images/p2p-setup/guide-p2p-setup-retrieval-method.png)

    ![P2P local-file policy](../images/p2p-setup/guide-p2p-setup-local-file-policy.png)

6. In `P2P Rebuild`, confirm that the expected first-device name is shown, then select `Sync`.

    ![Selecting the first device for P2P Rebuild](../images/p2p-setup/guide-p2p-setup-select-first-device.png)

7. On the first device, verify the requesting device name and select `Accept`. Use `Accept Temporarily` instead when approval should last only for this Obsidian session.

    ![Explicit P2P connection request on the first device](../images/p2p-setup/guide-p2p-setup-connection-request-1.png)

8. Keep both devices open until the test note appears on the second device.

    ![First-device note received by the second P2P device](../images/p2p-setup/guide-p2p-setup-first-to-second.png)

## Verify the return journey

Create a second ordinary note on the second device. With automatic broadcast disabled, start the next finite synchronisation explicitly:

1. Open the P2P Replicator pane on both devices.
2. If the previous finite peer connection no longer appears, select `Disconnect` and then `Open connection` on the first device, followed by the second device. The device which joins last is advertised to devices already in the room.
3. On the first device, select `Refresh`, verify the second-device name, then select `Replicate now`.
4. On the second device, verify the requesting first-device name and select `Accept` or `Accept Temporarily`.

    ![Explicit return-journey connection request on the second device](../images/p2p-setup/guide-p2p-setup-connection-request-2.png)

5. Confirm that the second-device note appears unchanged on the first device.

    ![Second-device note received by the first P2P device](../images/p2p-setup/guide-p2p-setup-second-to-first.png)

The two devices are now proven to share the same room, encryption settings, and data format in both directions. Configure automatic start, automatic broadcast, or optional features separately after this manual path works.

## If a peer does not appear

- Confirm that both panes show `Connected` and the same Room ID suffix.
- Select `Refresh` after the other device joins.
- Reconnect the device which should be discovered last.
- Check that the Setup URI came from the working first device and that neither device copied a peer name manually.
- Check relay reachability, WebRTC restrictions, VPNs, and TURN considerations in [Peer-to-Peer Synchronisation Tips](./tips/p2p-sync-tips.md).