Quick start

UniClipboard syncs through a space — a private, end-to-end encrypted group your devices belong to. The first device creates the space; every other device joins it with a short-lived invite code. There is no cloud account and no email — the space is the account.

This page takes you from a fresh install on two machines to your first synced paste.

What you'll need

UniClipboard installed on at least two devices. See Install for downloads.
A passphrase you'll remember. It protects every clip in the space and cannot be recovered if you lose it — that is the design, not a bug.
Both devices online at the same time. Any network works: the same Wi-Fi, different home networks, or a phone hotspot. Devices reach each other directly when they can, and fall back to an encrypted relay when they cannot.

The trust boundary is the space, not the individual device. Adding a third or fourth device later is the same flow as adding the second one — generate an invite, enter it on the new device.

Set up the first device

Launch the app and pick This is my first device

On first launch you'll see two options: This is my first device and I already use UniClipboard elsewhere. Pick the first.

Set a space passphrase

The passphrase is fed through Argon2id to derive your encryption key, which then encrypts every clip with XChaCha20-Poly1305. Pick something long and memorable — there is no reset flow, by design. Nothing about your space ever leaves the device unencrypted.

Choose when to connect another device

The All set screen confirms that your space is ready. Select Connect a device to create an invite now, or Do this later to open the dashboard. Anything you copy from then on is captured into the space and ready to sync when another device joins.

Add a second device

Have both devices in front of you — one to generate the invite, one to enter it.

On the first device, create an invite

If the All set screen is still open, select Connect a device. Otherwise, open Devices and select Generate invite code. The code is short-lived (valid for a few minutes), one-time, and does not carry your passphrase.

On the new device → I already use UniClipboard elsewhere

Enter the invite code together with the same passphrase you set on the first device. The passphrase is verified locally — a wrong passphrase fails fast and is never sent to the other device.

Wait for the first sync

Once the join completes, the new device's history catches up automatically. Both devices now show each other under Devices with an online indicator.

The CLI mirrors the GUI flow and is useful for headless servers, SSH sessions, and tmux-driven workflows.

# On the first device — skip if you already created the space in the GUI
uniclip init

# Generate a short-lived invite code
uniclip invite

# On the new device, paste the code from the previous step
uniclip join <code>

# Confirm both peers see each other
uniclip members

The daemon starts automatically. Use uniclip status to inspect it, or uniclip start / uniclip stop to control it explicitly.

Verify it works

On device A, copy any text — or an image, or a file.
Switch to device B and paste with Cmd+V / Ctrl+V, or open the quick panel with its keyboard shortcut and pick the entry.

If the paste shows up immediately, you're done. If it doesn't, Pairing & sync covers the transport (P2P hole-punching, encrypted relay fallback) and how to debug a stuck peer.

Add a phone (optional)

UniClipboard also supports an experimental HTTP companion for phones, useful for pasting between desktop and mobile. Mobile uses a different pairing path than desktops — it doesn't join the space's iroh trust mesh and doesn't get a node ID. It reaches the desktop on the LAN by default, or across networks via a server node or Tailscale. This LAN channel is being deprecated: the recommended path is to install the mobile app and pair it as a regular device instead.

On the desktop, open Devices → Other ways to add → Connect a phone over LAN and pick a label.
The credentials modal has two tabs, split by onboarding method:
- Scan to add — a connect-URI QR. Scan it from the UniClipboard iOS app (or any SyncClipboard-protocol client, including community Android apps) to auto-fill the base URL, username, and password.
- Install Shortcut — when the user doesn't have the UniClipboard iOS app, scan this QR to install the UniClipboard.shortcut, then manually paste the base URL, username, and password from the modal into its fields.
- For Android specifically, install the UniClipboard Android client at github.com/UniClipboard/UniClip, with APKs in releases (side-load only, no Google Play).
The plaintext password is shown once. If lost, use Rotate password on the device row to mint a new one without re-pairing.

Walkthrough and protocol details: Mobile sync (end-to-end setup), Pairing & sync — Mobile companion, and Mobile LAN API.

What's next

Add more devices. Repeat the second-device flow on every machine you want in the space. Each invite is one-time.
Try the quick panel. Invoke it with the configured shortcut for fast keyboard-driven access to recent clips — text, links, images, code, and files.
Switch spaces. From the Devices page or by running uniclip join --switch with another sponsor's invitation, e.g. to keep personal and work machines in separate spaces. Local history is re-encrypted under the new space's key during the switch.
Sync with a phone (experimental). See Mobile sync for the end-to-end walkthrough.

Upgrading from a pre-0.6 release? The underlying network stack was reworked, so old pairing state is no longer valid. Generate a fresh invite once and the devices will resume syncing.

On this page