FAQ

Privacy, deployment model, multi-device & multi-space, data, and upgrades — answered straight.

Answers below are grouped by topic. Each one leads with a one-line verdict, then the reasoning. If you're chasing a specific bug, jump to Troubleshooting instead.

Privacy & security

Where do my clips go? Who can see them?

Only between paired devices in your space, end-to-end encrypted the whole way.

The application layer encrypts with XChaCha20-Poly1305 using keys derived from the space MasterKey, independent of the transport. Traffic may go direct or through an encrypted relay — the relay only ever sees source / destination node IDs and ciphertext, never content.

Does UniClipboard run servers?

Only discovery (rendezvous) and an encrypted relay. Neither decrypts or persists your content:

Rendezvous maps node IDs to addresses, storing signed address records — think "DNS for peers".
Relay briefly forwards encrypted packets when P2P hole-punching fails.

Your clipboard history never lands on any of our servers. There is no "account cloud" and no cloud backup.

Diagnostics and usage analytics use separate channels for crash debugging and product reliability analysis. They do not carry clipboard content. See Privacy & data collection for the full field list.

What diagnostics or usage data does UniClipboard collect?

By default, UniClipboard collects two opt-out data categories: diagnostics (crashes, errors, anonymous logs, performance traces, and frontend diagnostics) and usage analytics (first-open, pairing funnel, and sync reliability events). They do not include clipboard content, file content, passphrases, or keys. See Privacy & data collection.

Can I recover a forgotten passphrase?

No. The passphrase derives the KEK via Argon2id, and the KEK wraps the space MasterKey. Nothing in the chain can be opened with a second key — that's the design goal and the price of having no backdoor.

If another device still has access to this space, revoke the lost one from there (or rebuild the space). If every device lost the passphrase, the only path is to abandon local history and init a new space.

On the unlock screen, Forgot passphrase? Reset and start over runs this from the GUI: it wipes the on-disk keyslot and KEK on this device, then drops you back at the setup screen so you can init a fresh space or join from another device. You'll have to type RESET to confirm — local history is unrecoverable after this point.

What if a relay gets compromised?

A compromised relay can affect performance and reachability, not confidentiality. The attacker sees ciphertext over QUIC plus end-to-end sealed envelopes — without the MasterKey, none of it is meaningful. See Pairing & sync — What the relay sees vs. what your peers see.

Is anything stored in plaintext on disk?

No. The local clipboard database and the full-text search index are both encrypted at rest, with keys held by the OS keyring (macOS Keychain / Windows Credential Manager / Linux Secret Service). See What syncs — Local storage.

Can I disable relay entirely?

Yes. Settings → Network → LAN-only mode disables the encrypted relay fallback (allow_relay_fallback = false under the hood). With it on, steady-state sync only goes through mDNS LAN discovery and direct (LAN / IPv6) paths:

never connects to any iroh relay (RelayMode::Disabled);
never publishes or resolves NodeId via the n0 public DNS (dns.iroh.link — pkarr publisher and DNS lookup are cleared);
even if a peer's stored address still carries a relay URL, the outbound dial strips it, so traffic won't be relayed via the peer's relay either.

Effect: peers are only reachable when they are on the same subnet and mDNS is reachable; already-paired devices on different networks become unreachable — that is the intended LAN-only contract.

The change requires a daemon restart to apply, and the tray icon reflects the LAN-only state.

Note: first-time pairing still goes through the public rendezvous (rendezvous.uniclipboard.app) to exchange NodeIds, so finish pairing in the default mode first, then enable LAN-only.

If you only want to make the current session direct, put both devices on a network where they can reach each other (same Wi-Fi, end-to-end IPv6, or shared VPN) without flipping the global toggle.

Deployment & accounts

Does it require an internet connection?

Only for pairing, cross-network discovery, and cross-network sync. Same-Wi-Fi sync runs P2P direct and works with the WAN cut entirely.

Is an email or account required?

There is no account system. The trust boundary is a space + a passphrase — no third-party identity provider involved. See Pairing & sync — Trust.

Can I self-host rendezvous / relay?

UniClipboard exposes custom iroh relay URLs in Settings → Network → Custom relay nodes. Leave the list empty to use the default iroh relays, or enter one relay URL per line to use only your own relay nodes. Restart the daemon after changing the list. For an end-to-end walkthrough of standing up a relay, see Self-hosting an iroh relay.

Custom rendezvous discovery is still not exposed. First-time pairing continues to use UniClipboard's rendezvous service, and cross-network NodeId discovery still uses the configured iroh discovery path unless LAN-only mode is enabled.

Multi-device & multi-space

How do "spaces" and "devices" relate?

Space = encryption boundary + shared history + a set of paired devices.
Device = an iroh node ID joined to one or more spaces.

After joining, the device holds the space's content keys and is treated as a trusted peer by every other device in the space.

Can one device join multiple spaces?

Yes, but only one is active at a time. Running uniclip join --switch with another sponsor's invitation (or the GUI's Devices page) re-encrypts local history under the new space's MasterKey before completing the switch — there is no plaintext window during the handoff.

Typical use: split "personal" and "work" devices into two spaces with different sensitivity levels.

How do I remove a device from a space?

Revoke it from another online device (GUI Devices page; CLI subcommand landing later). After revocation, peers refuse traffic from that node ID.

Wiping data on the device being removed doesn't revoke trust — only updates to the space's trusted set do.

Is adding the Nth device different from adding the second?

No. Each addition issues a one-time invite and uses it on the new device. There's no concept of a "primary" device. See Quick start — Add a second device.

Data & history

How long is history kept?

By default, a local retention policy (entry count + size thresholds) applies and old items are GC'd. Each device keeps its own history; deletes don't propagate across devices.

For finer-grained control by content type or per device, see What syncs — Per-device sync toggles.

Will a newly joined device receive my old history?

No. Pairing does not backfill history. Clips produced after the join propagate to the new device; everything before stays only on the device that originally captured it. This is intentional — joining is a clear time anchor, both for auditing and to prevent a freshly added device from siphoning the entire space history.

Does uninstalling clean everything?

No — uninstalling the package does not automatically clear the data directory or keyring entries. That's deliberate, to avoid accidental data loss. To wipe completely, follow Troubleshooting — Emergency reset.

Will an upgrade lose history?

Patch and minor upgrades preserve history. The 0.6 network stack rewrite was a breaking upgrade — old pairing state was invalidated but local history was kept; you just had to re-pair. Future breaking upgrades, if any, will be flagged in the release notes.

Can I export or back up history?

Yes. The GUI offers Export config under Settings → Storage → Config backup / migration, which packages the current device's history, settings, identity, and key material into an encrypted .ucbundle file (protected by your Space passphrase — no extra password to set); Import config on another machine restores it — pairings included, so no re-pairing. Import replaces whatever config is on the target, so it works on a fresh install or an in-use one (it overwrites it). For the full steps and the "move" semantics, see Export & import config.

Under the hood the hidden uniclip dev dump-clipboard --limit N still exists for development purposes and may change. Plain-copying the data directory for a mirror backup is unreliable: the database is encrypted, key storage differs across install forms, and copying files won't carry the identity — for a cross-machine restore use the export / import above.

Platforms & versions

Is there a mobile app?

On iOS, the UniClipboard iOS App is now in TestFlight public beta. Invite link: testflight.apple.com/join/nyNQ8dQe — install TestFlight from the App Store, then open the link to accept and install the beta build (full walkthrough plus the proxy/VPN gotchas is in Mobile sync — Pair an iPhone).

On Android, install the UniClipboard Android client at github.com/UniClipboard/UniClip, with APKs published in releases (side-load only, no Google Play). Any other SyncClipboard-compatible client can also connect by entering the same base URL + credentials.

Either way, mobile sync runs as an HTTP companion: the desktop daemon exposes a SyncClipboard-compatible HTTP service, and the mobile client talks to it with base URL + Basic Auth. The bundled iOS Shortcut remains available as a fallback.

What "companion" means in practice:

Bidirectional. Desktop → mobile and mobile → desktop both work.
Not P2P. Mobile sync runs over plain HTTP — there is no iroh P2P, no NAT hole-punching, and no encrypted relay on the mobile side. It works on the LAN out of the box; for cross-network reach, run a headless server node (a public HTTPS endpoint) or use a Tailscale / VPN overlay.
Mobile is not a peer. Mobile devices don't join the space's trust mesh and don't sync between each other; they exchange clipboard with whichever desktop they're paired to.

See the Mobile sync guide for the end-to-end setup flow, Mobile LAN API for the protocol surface, and Pairing & sync — Mobile companion for the pairing UI.

Why can't the iOS app sync clipboard silently in the background like the desktop?

It's an iOS platform restriction, not something we can engineer around. iOS does not grant third-party apps a general-purpose background hook for reading the clipboard. UIPasteboard reads are only reliable while an app is in the foreground; suspended apps don't get a wake-up when the system clipboard changes, and silent background polling would be killed by the scheduler (and would also trip the system pasted from <app> banner every time).

What this means in practice for the UniClipboard iOS app:

Foreground only on the receive path. New clips from desktop arrive in the app once you bring it to the foreground (or via a notification tap when one is delivered). There is no truly silent always-on sync the way desktops do it.
Sending requires user intent. Copies made in other iOS apps do not stream out automatically — you open UniClipboard (or the iOS Shortcut) to push the current pasteboard.
Even big vendors hit the same wall. WeChat's keyboard, for example, can only sync clipboard at the moment the keyboard is invoked. iOS's sandboxing is strict here regardless of who ships the app.

A possible future direction is a keyboard / input-panel style companion — switching to UniClipboard's panel would give iOS a legitimate window to read and push clipboard content. This is being explored but not committed; it would not turn into "silent always-on background sync" either, because the underlying OS constraint doesn't change.

If you need true always-on clipboard sync, use a desktop (macOS, Windows, Linux) as the peer. The iOS app is best treated as an on-demand companion to that.