This guide explains how Hypermark synchronizes your bookmarks between devices using a combination of peer-to-peer and cloud-based technology.
- Overview
- Getting Started
- Device Pairing
- Understanding Sync
- Relay Configuration
- Sync Indicators
- Troubleshooting
- Privacy & Security
- FAQ
Hypermark uses a dual-sync approach to keep your bookmarks synchronized across all your devices:
- P2P Sync (WebRTC): Real-time sync when devices are online simultaneously
- Cloud Sync (Nostr): Asynchronous sync via encrypted messages stored on decentralized relays
This combination ensures your bookmarks stay in sync whether your devices are online at the same time or not.
- No account required: Your devices pair directly using a secure code
- End-to-end encrypted: Only your devices can read your bookmarks
- Decentralized: No single server controls your data
- Conflict-free: Simultaneous edits on different devices are automatically merged
- Open Hypermark on your first device
- Go to Settings > Device pairing
- Click Show Pairing Code
- A code will appear (e.g.,
42-apple-river)
On your second device:
- Open Hypermark
- Go to Settings > Device pairing
- Click Enter Pairing Code
- Type the code exactly as shown on the first device
- Wait for the "Pairing Complete" confirmation
Your devices are now securely linked and will sync automatically.
Device pairing establishes a secure connection between your devices without requiring any account or password. The pairing code (e.g., 42-apple-river) creates a temporary encrypted channel for exchanging cryptographic keys.
The pairing code has three parts:
- A number (1-999): Identifies the connection room
- Two words: Provide the encryption password
On the device with your bookmarks (Source device):
- Go to Settings > Device pairing
- Select Show Pairing Code
- A unique code will be displayed
- Keep this screen open while you set up the other device
On the new device:
- Go to Settings > Device pairing
- Select Enter Pairing Code
- Enter the code exactly as shown
- Click Connect
The devices will:
- Establish a secure connection
- Exchange encryption keys
- Begin syncing your bookmarks
- Code expires in 5 minutes: If the pairing times out, generate a new code
- Case-insensitive: Uppercase and lowercase don't matter
- Exact match required: Enter the code exactly as displayed
Repeat the process for each new device. Any already-paired device can act as the source device to pair additional ones.
Everything in your bookmarks is synchronized:
- Bookmark titles
- URLs
- Tags
- Descriptions
- Read-later status
- Last modified timestamps
When multiple devices are online simultaneously:
- Changes are sent directly between devices
- Sync happens in real-time (sub-second)
- Indicated by the P2P status showing connected devices
When devices are not online at the same time:
- Changes are encrypted and published to Nostr relays
- Other devices fetch changes when they come online
- Changes are debounced (collected for 1.5 seconds before publishing)
Hypermark uses CRDT (Conflict-free Replicated Data Type) technology to handle conflicts automatically:
| Scenario | What Happens |
|---|---|
| Edit title on Device A, add tag on Device B | Both changes are preserved |
| Edit same field on both devices | Changes are merged deterministically |
| Delete on one device, edit on another | Delete wins |
| Create same bookmark simultaneously | Both are preserved with unique IDs |
You never need to manually resolve conflicts.
Nostr relays are servers that store and forward your encrypted bookmark data. Think of them as message delivery services. Your bookmarks are encrypted before being sent, so relay operators cannot read your data.
Hypermark connects to several public relays by default:
wss://relay.damus.iowss://nos.lolwss://relay.nostr.bandwss://nostr-pub.wellorder.netwss://relay.current.fyi
Using multiple relays provides:
- Redundancy: If one relay is down, others still work
- Reliability: Better chances your data is always accessible
- Performance: Connections to geographically closer relays may be faster
To configure relays:
- Go to Settings > Cloud Sync (Nostr) > Configure relays
- You'll see a list of all connected relays
Testing a relay:
- Click the lightning bolt icon next to any relay
- Shows connection status and latency
Adding a custom relay:
- Click Add
- Enter the WebSocket URL (must start with
wss://orws://) - Optionally test the connection
- Click Add Relay
Removing a custom relay:
- Click the trash icon next to any custom relay
- Default relays cannot be removed
| Icon | Meaning |
|---|---|
| Green checkmark | Connected |
| Red X | Connection failed |
| Yellow spinning | Connecting |
| Gray server | Not tested |
Latency colors:
- Green: Excellent (<100ms)
- Yellow: Good (100-300ms)
- Red: Acceptable but slower (>300ms)
In Settings > Cloud Sync (Nostr), you'll see:
Relay connection:
- Cloud icon with status indicator
- Number of connected relays (e.g., "4/5 relays connected")
Last sync:
- Shows when the last sync activity occurred
- "Just now", "5m ago", "1h ago", etc.
Pending updates:
- Shows number of changes waiting to be synced
- "0 pending" means everything is synced
- "3 pending" means 3 changes are queued
| Color | Meaning |
|---|---|
| Green | Connected and syncing |
| Yellow | Connecting or syncing in progress |
| Gray | Not connected |
| Red | Error (check diagnostics) |
Go to Settings > Cloud Sync (Nostr) > Sync diagnostics for comprehensive troubleshooting tools.
Overview tab:
- Shows system health at a glance
- Run diagnostics to check all components
- View your Nostr public key (fingerprint)
Troubleshoot tab:
- Automated suggestions based on detected issues
- Common issues and solutions
History tab:
- View recent sync activity
- Helpful for debugging sync issues
- Check that sync is enabled in Settings > Cloud Sync (Nostr)
- Verify at least one relay is connected (green status)
- Ensure your device is paired (has encryption keys)
- Try clicking Sync to force a sync
After pairing a new device:
- Wait a few moments for initial sync
- Check that relays are connected
- Bookmarks sync through relays, which may take time if you have many
- Go to Configure relays and test each relay
- Some relays may be temporarily unavailable
- Add additional relays for redundancy
- Check your internet connection
- Changes are debounced (1.5 second delay before publishing)
- Check the "pending" counter in Settings
- If updates stay pending, there may be a connection issue
- Try Sync to force pending changes
- Ensure you entered the code exactly as shown
- Check internet connection on both devices
- The code expires after 5 minutes - get a new one
- Both devices must be on the same Hypermark version
For advanced troubleshooting:
- Go to Sync diagnostics
- Click Export
- A JSON file will download with detailed diagnostic information
Your bookmarks are protected by multiple layers of encryption:
| Layer | What It Protects |
|---|---|
| LEK (Ledger Encryption Key) | Encrypts all bookmark content |
| AES-256-GCM | Industry-standard encryption algorithm |
| Transport (TLS/WSS) | Encrypts data in transit |
Relays CAN see:
- Your public key (same on all your devices)
- Bookmark IDs (not the content)
- Timestamps
- Sync frequency
Relays CANNOT see:
- Bookmark URLs
- Titles
- Tags
- Any content
- No email, username, or password required
- No analytics or tracking
- Your identity is just a cryptographic key
- Different from every other user
The LEK (Ledger Encryption Key) is:
- Generated locally on your first device
- Transferred securely during pairing
- Never sent to any server unencrypted
- Stored only on your paired devices
- No account required: No email, password, or sign-up
- You control your data: Stored on decentralized relays
- True encryption: Even relay operators can't read your bookmarks
- Cross-browser: Works across different browsers and devices
Yes. Pair as many devices as you want. All paired devices share the same encryption key and stay in sync.
Your bookmarks remain safe on other paired devices and relays. The lost device cannot access your bookmarks without the encryption key stored on it.
If you're concerned about security, there's no way to "revoke" a device's access since there are no accounts. However, bookmarks are only accessible if someone has both:
- Physical access to the device
- Access to the browser storage
Yes. You can run your own Nostr relay and add it in Configure relays. This gives you complete control over where your encrypted data is stored.
Each bookmark is stored as an individual encrypted event. Relays automatically keep only the latest version of each bookmark (using Nostr's "replaceable events" feature).
- Local changes: Always saved immediately
- P2P sync: Requires both devices online
- Cloud sync: Changes queued and published when connected
When you come back online, pending changes are automatically synced.
This is why Hypermark uses multiple relays. As long as at least one relay has your data, you can sync. Adding more relays increases redundancy.
Currently, there's no way to "unpair" a device. You can:
- Clear the browser data/storage on that device
- Uninstall Hypermark from that device
The device will no longer have the encryption key and cannot sync.
Your bookmarks are stored on:
- Each paired device (locally)
- All connected Nostr relays (encrypted)
For additional backup, you can export your bookmarks (coming soon).