UniClipboard

UniClipboard

English | 简体中文 | 繁體中文 | 日本語 | Русский | Português (Brasil)

Who maintains this project? (About & Trust)

Normal mode keeps the tray, Quick Panel, and global shortcuts available. Lightweight mode keeps only the synchronization daemon running after you close its temporary main window. Background startup controls whether automatic login launch opens the main window; opening the app manually always lets you access history and settings. Closing the main window releases its WebView; an active fallback Quick Panel can retain its own resources.

Project Overview

Copy on one device. Paste on another — even across the internet.

No cloud account. No third-party servers. Your clipboard never leaves your devices in a form anyone else can read.

UniClipboard is a privacy-first clipboard tool. It keeps a searchable, encrypted history of everything you copy, brings it back instantly through the Quick Panel, and syncs text, images, and files across your devices, whether they are on the same Wi-Fi or on different networks. Clipboard content is end-to-end encrypted in transit and stays encrypted at rest; it is decrypted only on your own devices, so relays and the network in between only ever see ciphertext.

Desktop ↔ desktop — real-time, bidirectional clipboard sync between two computers.

Important

Upgrading from 0.19.x? 1.0 is a breaking upgrade: local data is converted to a new format (you cannot downgrade to 0.19 afterwards), and every device must run 1.0 and be paired again before syncing resumes. Read the 0.19 → 1.0 upgrade guide before upgrading.

Table of Contents

• Features
• Installation
  • Download from Releases
  • One-line install script (Linux / macOS)
  • Linux
  • Homebrew (macOS)
  • Upgrading from 0.19.x
  • Build from Source
• Usage
  • First Device (Create a Space)
  • Adding More Devices (Join via Invitation)
  • Connect a Phone
  • Main Pages
• Advanced Features
  • How it Works
  • Command-line Tool
  • Privacy & Security
• FAQ
• Contributing
• License
• Acknowledgments
• Community

Features

• Desktop apps for Windows, macOS, and Linux: Native installers for x86_64 and ARM64 (Apple Silicon / Intel on macOS), plus a standalone uniclip CLI.
• Local full-text search: Search your whole history quickly with suggestions and keyboard completion — the search index itself stays encrypted on disk.
• Quick Panel: A keyboard-shortcut overlay with inline previews for text, links, images, code, and files. On Linux desktops without global shortcuts, it can be opened from a desktop shortcut instead.
• Cross-network sync: Desktop devices sync directly on the same network or across the internet with automatic NAT traversal, falling back to an encrypted relay when no direct path exists. You can also add your own relay servers.
• Encrypted spaces: Devices join a shared "space" with a short-lived invitation code plus the space passphrase — no cloud account, no email.
• Text, images, and files: Copy on one device, paste on another. Large files are streamed, incoming transfers continue after an app restart, and multi-item transfers show combined progress and can be cancelled.
• Per-device sync control: Choose which content types each paired device sends and receives, pause all sync or automatic sync separately (manual sending still works), and toggle sync per device from the tray menu. A device that comes back online receives the latest item it missed.
• Command-line tool: uniclip covers setup, pairing, sending, receiving, and member management headlessly — built for terminals, SSH sessions, scripts, and servers.
• Multi-device management: See each device's connection state, adjust per-device sync preferences, and remove a lost device from any other paired one.
• Safe upgrades and recovery: Local data is backed up automatically before upgrades. If the system-stored key is lost, you can recover with the original space passphrase.
• Mobile apps: The UniClipboard mobile app for iOS and Android connects to your desktop — see Connect a Phone.
• Localized UI: English, Simplified Chinese, Traditional Chinese, Japanese, Russian, and Brazilian Portuguese.

Installation

Install through your preferred package manager, or choose a download option below. Version badges link to the published packages.

Platform	Package manager	Current version	Install command
macOS	Homebrew		brew install --cask uniclipboard
Windows	WinGet		winget install --id UniClipboard.UniClipboard -e
Windows	Scoop		scoop install extras/uniclipboard
Windows	Chocolatey		choco install uniclipboard
Arch Linux	AUR		yay -S uniclipboard-git
Linux	Snap		sudo snap install uniclipboard
macOS / Windows / Linux	npm (CLI)		npm install -g @uniclipboard/cli
Linux	Flathub		Not yet published

Scoop requires the Extras bucket (scoop bucket add extras). AUR tracks the main branch. Flathub is not published yet.

Download from Releases

Download the latest version from GitHub Releases:

Every release ships .sig signature files and a signed SHA256SUMS.txt for verification.

One-line install script (Linux / macOS)

Don't want to pick a package by hand? One command does it:

curl -fsSL https://uniclipboard.app/install.sh | bash

The script installs the latest stable release and detects OS and CPU automatically:

• macOS — downloads .app.tar.gz, extracts it, and moves UniClipboard.app into /Applications (escalates with sudo if the directory isn't writable; pass --prefix "$HOME/Applications" for a user-level install).
• Linux — with sudo, installs the .deb on apt-based systems or uses the COPR repository on dnf-based systems (Ubuntu 20.04 uses the Snap package); otherwise falls back to AppImage in ~/.local/bin with a .desktop entry (no root needed).

Common flags:

# Pin a specific version
curl -fsSL https://uniclipboard.app/install.sh | bash -s -- --version v1.0.1

# Force AppImage (rootless even when sudo is available)
curl -fsSL https://uniclipboard.app/install.sh | bash -s -- --format appimage

Uninstall with the matching script:

# Remove the app only, keep data and config
curl -fsSL https://raw.githubusercontent.com/UniClipboard/UniClipboard/main/scripts/uninstall.sh | bash

# Full wipe — also removes data directories, config, and cache
curl -fsSL https://raw.githubusercontent.com/UniClipboard/UniClipboard/main/scripts/uninstall.sh | bash -s -- --purge

# Preview what would be removed without deleting anything
curl -fsSL https://raw.githubusercontent.com/UniClipboard/UniClipboard/main/scripts/uninstall.sh | bash -s -- --dry-run

Update behavior matches the manual download paths below: .deb / .rpm / COPR / Snap installs are updated by your system package manager, not the in-app updater. AppImage on Linux and .app on macOS update from inside the app.

Linux

Each release ships .deb, .rpm, and .AppImage artifacts for both x86_64 and aarch64.

Fedora / RHEL / openSUSE — via COPR (recommended, auto-updating)

sudo dnf copr enable mkdir700/uniclipboard         # stable; mkdir700/uniclipboard-alpha for pre-releases
sudo dnf install uniclipboard

After enabling, sudo dnf upgrade will pick up new releases automatically.

Snap

sudo snap install uniclipboard

Nix (x86_64 and aarch64, experimental)

nix run github:UniClipboard/UniClipboard          # try it
nix profile add github:UniClipboard/UniClipboard  # install (older Nix: nix profile install)

These commands need the nix-command and flakes experimental features. The flake repackages the released .deb and currently pins a pre-release (see packaging/nix/README.md for the NixOS setup, known gaps and the validation status). Update through Nix, not the in-app updater, and do not use the in-app launch-at-login switch on a Nix install.

Or download a single .rpm / .deb / AppImage from the Releases page:

# Debian / Ubuntu
sudo dpkg -i UniClipboard_<version>_amd64.deb
sudo apt-get install -f                                 # resolve missing deps if any

# Fedora / RHEL / openSUSE (one-shot, no COPR)
sudo dnf install ./UniClipboard-<version>-1.x86_64.rpm

# AppImage (any distro)
chmod +x UniClipboard_<version>_amd64.AppImage
./UniClipboard_<version>_amd64.AppImage

Packaged installs (COPR / Snap / rpm / deb) do not auto-update from inside the app — use your package manager. The AppImage is what the in-app updater uses on Linux.

Homebrew (macOS)

On macOS, install via the official tap UniClipboard/homebrew-tap:

brew tap UniClipboard/tap

# Homebrew 6.0+ requires you to trust third-party taps before it will load
# their formulae/casks. Skip this and you'll hit
# "Refusing to load ... from untrusted tap". It only needs to run once.
brew trust UniClipboard/tap

# Desktop app (.app bundle)
brew install --cask uniclipboard

# CLI only — installs the `uniclip` command
brew install uniclipboard

Or install in a single command without tapping first (still trust the tap once):

brew trust UniClipboard/tap                          # Homebrew 6.0+, one-time
brew install --cask UniClipboard/tap/uniclipboard    # GUI
brew install UniClipboard/tap/uniclipboard           # CLI

The cask and the formula can coexist — install both if you want the GUI plus the uniclip command.

Upgrading from 0.19.x

1.0 converts local data to a new storage and protection format and uses a new pairing scheme:

• Upgrade in place with the same installation style; history is backed up automatically on first launch, which takes longer than usual.
• You cannot downgrade to 0.19 afterwards, and 0.19 and 1.0 devices cannot sync with each other.
• After upgrading, old pairings are cleared. Once every device runs 1.0, pair them again from the Devices page.

Follow the 0.19 → 1.0 upgrade guide for the recommended order, backup locations, and recovery steps.

Build from Source

Prerequisites: the Rust toolchain (pinned by rust-toolchain.toml), Bun, Go (version in apps/gui-go/go.mod), and the Wails v3 prerequisites for your OS. The development command bun wails:dev supports macOS and Windows.

git clone https://github.com/UniClipboard/UniClipboard.git
cd UniClipboard

# Install dependencies
bun install

# Start development mode (isolated `dev` profile, so it doesn't touch an installed app's data)
bun wails:dev

# Build a local macOS app bundle
apps/gui-go/build.sh

The bundle layout is described in apps/gui-go/README.md. See CONTRIBUTING.md for multi-peer development, tests, and project conventions.

Usage

First Device (Create a Space)

1. Launch the app, choose This is my first device, and click Start new space.
2. Set an encryption passphrase — it protects all data in the space and is needed to add devices, so keep it safe.
3. Done. Copied content is stored encrypted in this space.

Adding More Devices (Join via Invitation)

1. On an existing device, open the Devices page and click Invite Device to generate a short-lived invitation code.
2. On the new device, choose I already use UniClipboard elsewhere → Join via pairing, then enter the invitation code together with the space passphrase.
3. Once the pairing is confirmed, the device joins and syncing starts automatically.

Already set up and want to move to another space? Use Join another space on the Devices page (or run uniclip space join --switch from the CLI); your local clipboard history is migrated to the new space. Without --switch, uniclip space join takes the non-destructive re-pair path and does not switch spaces.

Connect a Phone

The UniClipboard mobile app covers iOS (TestFlight public beta) and Android (APK downloads). On the desktop, open Devices and click the phone icon to open Connect phone, which offers two methods:

• Regular sync (default) — an HTTP compatibility mode. The desktop daemon runs a small SyncClipboard-compatible HTTP service; the dialog registers the phone and shows a QR code with the address and one-time credentials for the app to scan.
• Device connection (Experimental) — the phone joins your encrypted space with an invitation code, like another desktop.

Regular sync limitations:

• Not P2P — the phone is a plain HTTP client with no NAT traversal or relay. It works on the local network; for other networks, use a headless server node (public HTTPS) or a Tailscale / VPN overlay.
• Plain HTTP + Basic Auth at the listener — only enable it on networks you trust, or put it behind a TLS reverse proxy.
• The phone is not a space member — it gets no node ID and cannot read the encrypted history database.
• No silent background sync on iOS — iOS doesn't give apps a general-purpose background clipboard hook, so the iOS app syncs while in the foreground or through its keyboard and share extensions. See [FAQ — iOS background sync](https://docs.uniclipboard.app/help/faq#why-cant-the-ios-app-sync-clipboard-silently-in-the-background-like-th