ClipCascade is an open-source, lightweight utility that automatically syncs your clipboard across multiple devices—no key press required. It ensures seamless clipboard sharing between devices, prioritizing privacy with end-to-end encryption. Whether you're moving between workstations or simply want the convenience of a unified clipboard, ClipCascade has you covered.
| Docker | Windows | macOS | Android | Linux |
|---|---|---|---|---|
|
|
|
|
|
| 🪟 Desktop (Windows) | 🍏 Desktop (macOS) | 🤖📱 Mobile (Android) | 🐧🖱️ Desktop (Linux_GUI) | 🐧⌨️ Desktop (Linux_non-GUI) |
|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
- 🔒 Secure Login Authentication: Your data is safe. Login authentication ensures that only authorized users can access the clipboard sync.
- 🚀 Live Sync: Clipboard content syncs across your devices instantly, without needing any key press—just copy, and it's there!
- 💻 Desktop Application: A native desktop application for Windows, macOS and Linux, offering effortless setup and user-friendly operation.
- 📱 Mobile Application: Access your clipboard sync seamlessly on Android devices with a dedicated mobile app.
- 📦 Self-Hosted Docker Image: Host your own instance of ClipCascade effortlessly using the provided Docker image.
- 🛡️ Privacy by Encryption: Your clipboard data is end-to-end encrypted, ensuring that only you can access it.
- 🌐 Web-Based Monitoring: Monitor your clipboard activity in real-time via a sleek web interface.
- ⚙️ Advanced Settings: Customize your clipboard sync experience with additional settings for fine-tuning performance.
- 🔔 Update Notifications: Stay informed with timely update notifications across all platforms, keeping your app up to date with the latest features and security enhancements.
To host ClipCascade on your server, use Docker with the following steps:
- Create a
docker-compose.ymlfile with the following content:version: '3.8' services: clipcascade: image: sathvikrao/clipcascade:latest ports: - "8080:8080" restart: always environment: - CC_USERNAME=user #username - CC_PASSWORD=pass123 #password - CC_MAX_MESSAGE_SIZE=1 #MiB (desktop(windows) < 25 MiB, mobile(android) ~ 1 MiB)
- Run the Docker container using Docker Compose:
docker-compose up -d - Access the web-based monitoring page at
http://localhost:8080.
To host the ClipCascade server on any operating system that supports Java 17 or higher, follow these steps:
-
Download the JAR File
Copy theClipCascade-0.0.1-SNAPSHOT.jarfrom the release page. -
Set Environment Variables
Set the following environment variables in your OS:Variable Value CC_USERNAMEyour-user-name CC_PASSWORDyour-password CC_MAX_MESSAGE_SIZE1 -
Run the Server
Execute the following command in your terminal:java -jar ClipCascade-0.0.1-SNAPSHOT.jar
-
Access the Server
You can access the ClipCascade server athttp://localhost:8080.
To install the Windows desktop application, download the latest version from the Releases page.
- Download the installer from the Releases page.
- Run the installer and follow the on-screen instructions, and select the default installation path specified by the installer.
- Startup is enabled by default; you can disable it in the Task Manager if desired.
- Launch ClipCascade and log in to start syncing your clipboard across devices.
- When prompted for the server connection, use the server IP and port, appending
/clipsocketfor the WebSocket connection (e.g.,ws://<server_ip>:<server_port>/clipsocket). - If encryption is enabled, please ensure it is enabled on all devices.
- When prompted for the server connection, use the server IP and port, appending
Important Note: Since the application is not published or registered with Microsoft, you may see a warning suggesting that it could be unsafe. This is a standard precaution and does not indicate any issues with the software. You can choose to ignore this warning or temporarily disable your antivirus during installation. All source code is available in this repository, and everything is open source and free. If you prefer, you can compile the executable yourself. Feel free to review the code to ensure your comfort! Registering the application with Microsoft requires purchasing a certificate subscription, which is quite expensive, especially for an open-source project.
The .exe file does not need UAC approval because it is standalone executable, while the .msi installer will request UAC permissions because it creates a designated folder for the software, adds a startup option, and allows for uninstallation via the Control Panel. Additionally, with the .msi installer, you have the option to choose any location to save the software. However, select locations where even when you create a file manually at that location, Windows shouldn’t prompt for permission to answer "yes or no" questions.
To install the macOS desktop application, download the latest version from the Releases page.
-
Download the appropriate version:
- For M-series chips, download
ClipCascade-Apple_macOS(ARM_M-Series).zip. - For Intel chips, download
ClipCascade-Apple_macOS(Intel-Series).zip.
You can check your chip type by going to About This Mac.
- For M-series chips, download
-
Extract the contents:
- Double-click on the
.zipfile to extract the files.
- Double-click on the
-
Navigate to the extracted folder.
-
You will find the ClipCascade application inside. You can move this application to any location you prefer on your system.
-
First-time launch (see note below for more information):
-
Right-click (not double-click) on the ClipCascade application and select Open.
-
If you encounter the warning "Apple could not verify 'ClipCascade' is free...", click Done or Ok. (Apple Guide)
-
Go to System Preferences > Security & Privacy > Click Open Anyway (if you see the option), and when you re-run(right click->open) the application warning prompt reappears one last time, click Open Anyway or Open. (Apple Guide)
-
-
-
Wait for the app to launch: When you open the application, macOS will scan the application. This may take 10–30 seconds.
-
Connect to the server:
- When prompted, enter the server IP and port, appending
/clipsocketfor the WebSocket connection (e.g.,ws://<server_ip>:<server_port>/clipsocket). - If encryption is enabled, ensure it is enabled on all devices.
- When prompted, enter the server IP and port, appending
-
Once logged in, the application will run in the menu bar with a clipboard icon at the top of your screen.
-
Set ClipCascade to start on login (Startup):
-
Right-click the ClipCascade icon in the dock (bottom of the screen).
-
Select Options and then check Open at Login.
-
Important Note: Since the application is not published or registered with Apple, you may see a warning suggesting that it could be unsafe. This is a standard precaution and does not indicate any issues with the software. You can choose to ignore this warning. All source code is available in this repository, and everything is open source and free. If you prefer, you can compile the executable yourself. Feel free to review the code to ensure your comfort! Registering the application with Apple requires purchasing a certificate subscription, which is quite expensive, especially for an open-source project.
To install the mobile application on your Android device, download the latest APK from the Releases page.
- Download the APK from the Releases page.
- Enable installation from unknown sources in your device settings, if prompted.
- Install the APK by following the prompts on your device.
- Open ClipCascade and log in to begin syncing your clipboard across devices.
- When prompted for the server connection, use the server IP and port, appending
/clipsocketfor the WebSocket connection (e.g.,ws://<server_ip>:<server_port>/clipsocket). - If encryption is enabled, please ensure it is enabled on all devices.
- When prompted for the server connection, use the server IP and port, appending
To enable automatic clipboard monitoring on both rooted and non-rooted devices, execute the following three ADB commands.
Before proceeding, make sure ADB is installed on your system. Follow the instructions here to install ADB on Windows, macOS, or Linux.
-
Enable the
READ_LOGSpermission:adb -d shell pm grant com.clipcascade android.permission.READ_LOGS
-
Allow "Display/Drawing over other apps," "Screen overlay," or "Appear on top": This permission can also be enabled from the device's Settings. To set it via ADB, use:
adb -d shell appops set com.clipcascade SYSTEM_ALERT_WINDOW allow -
Kill the app for the new permissions to take effect:
adb -d shell am force-stop com.clipcascade
Once the setup is complete, it operates seamlessly without requiring any extra steps. It monitors log entries related to ClipCascade, and if it detects an error during a clipboard copy action, it will trigger an overlay window to gain focus. This overlay allows the app to capture the clipboard content and send it to the server immediately before going out of focus and closing. When the app is uninstalled, these permissions will be removed, requiring you to redo these steps. Additionally, each time you start the foreground service, it will prompt you to choose whether to monitor logs. This ensures that everything remains secure and under your control.
After executing three ADB commands, when you click the Start button, you will see a pop-up message. Click "Allow."
This guide provides step-by-step instructions to install ClipCascade on Debian/Ubuntu and Fedora-based systems. While the commands are tailored for these distributions, the process can be adapted for other Linux distros with some tweaks. You can find the code for Linux in the Releases page as ClipCascade_Linux.zip. Navigate to the ClipCascade/ folder, where you can find main.py, and open the terminal in that location.
Important Note: ClipCascade GUI may not function on Wayland-only distributions. If you encounter any issues, please consider using an X11 session or a terminal-based implementation, which is available for users who experience difficulties with the GUI setup. see here
sudo apt update
sudo apt install -y python3 python3-pip python3-gi xclip
sudo dnf check-update
sudo dnf install -y python3 python3-pip python3-gobject xclip dunst
Run the following command to install the dependencies listed in requirements.txt:
sudo pip3 install -r requirements.txt
If you encounter the error: externally-managed-environment, install the required Python packages manually:
sudo apt install -y python3-xxhash python3-pyperclip python3-requests python3-websocket python3-pycryptodome python3-tk python3-pystray python3-plyer
sudo dnf install -y python3-xxhash python3-pyperclip python3-requests python3-websocket-client python3-pycryptodome python3-tkinter python3-pystray python3-plyer
sudo apt install -y python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdk-3.0
sudo dnf install -y libappindicator-gtk3
Note: If the tray icon is not available on GNOME-based systems like Fedora, you may need to install the GNOME tray support extension: GNOME AppIndicator Support
Start ClipCascade by running:
sudo python3 main.py
If you encounter the No module named 'Crypto' error, create a symbolic link for the Cryptodome library:
see more
sudo ln -s /usr/lib/python3/dist-packages/Cryptodome /usr/lib/python3/dist-packages/Crypto
sudo ln -s /usr/lib/python3/site-packages/Cryptodome /usr/lib/python3/site-packages/Crypto
If you encounter the No module named 'tkinter' error:
sudo apt install -y python3-tkinter
sudo dnf install -y python3-tkinter
Step 4.3: Fix 'gtk_widget_get_scale_factor: assertion 'GTK_IS_WIDGET (widget)' failed' Error (if applicable)
This error may be caused by a missing tray icon extension in GNOME. To fix it, you can install the AppIndicator Support extension by visiting this link
sudo apt install dbus-x11
sudo dnf install dbus-x11
To run ClipCascade as a background process:
sudo nohup python3 main.py &> /dev/null &
To ensure ClipCascade starts automatically when your system boots, modify the path as necessary and add the following to your startup script:
cd /path/to/clipcascade/src/ && sudo nohup python3 main.py &> /dev/null &
Note: If clipboard monitoring doesn't work without `sudo`, ensure you are running the application with elevated privileges.
This guide provides step-by-step instructions to install ClipCascade on Arch, Debian/Ubuntu and Fedora-based systems. While the commands are tailored for these distributions, the process can be adapted for other Linux distros with some tweaks. You can find the code for Linux in the Releases page as ClipCascade_Linux_Terminal.zip. Navigate to the ClipCascade/ folder, where you can find main.py, and open the terminal in that location.
Note: A GUI-based implementation is available for users who prefer a more intuitive, visual interface over the terminal setup. see here
sudo pacman -Syu --noconfirm python python-pip python-gobject xclip
sudo apt update
sudo apt install -y python3 python3-pip python3-gi xclip
sudo dnf check-update
sudo dnf install -y python3 python3-pip python3-gobject xclip
Run the following command to install the dependencies listed in requirements.txt:
sudo pip3 install -r requirements.txt
If you encounter the error: externally-managed-environment, install the required Python packages manually:
sudo pacman -S --noconfirm python-xxhash python-pyperclip python-requests python-websocket-client python-pycryptodome python-pyfiglet
sudo apt install -y python3-xxhash python3-pyperclip python3-requests python3-websocket python3-pycryptodome python3-pyfiglet
sudo dnf install -y python3-xxhash python3-pyperclip python3-requests python3-websocket-client python3-pycryptodome python3-pyfiglet
If you encounter difficulties or errors while performing Step 3, you can skip it and proceed to Step 4.
sudo pacman -S --noconfirm python-gobject gtk3
sudo apt install -y python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdk-3.0
sudo dnf install -y libappindicator-gtk3
Start ClipCascade by running:
sudo python3 main.py
Step 4.1: Fix 'Error: Can't open display: :1 - Authorization required, but no authorization protocol specified' Error (if applicable)
Run python3 main.py without using sudo
If you encounter the No module named 'Crypto' error, create a symbolic link for the Cryptodome library:
see more
sudo ln -s /usr/lib/python3/dist-packages/Cryptodome /usr/lib/python3/dist-packages/Crypto
sudo ln -s /usr/lib/python3/site-packages/Cryptodome /usr/lib/python3/site-packages/Crypto
sudo apt install dbus-x11
sudo dnf install dbus-x11
Note: If clipboard monitoring doesn't work without `sudo`, ensure you are running the application with elevated privileges.
- Logs (
clipcascade_log.log) are present in the installed path, allowing you to review application activity. These logs reset upon reopening the application, so they don’t grow indefinitely. - You can customize advanced settings in the DATA file, which is also located in the installed path. This file is generated only after your first login and remains there indefinitely.
- On Linux, you will see a
ClipCascade.lockfile while the program is running. This file prevents the user from opening multiple instances of ClipCascade.
-
Program files are located in
<current user>/Library/Application Support/ClipCascade/. To open it, click Program Files.
-
Logs (
clipcascade_log.log): Review application activity. These logs reset upon reopening the application to prevent them from growing indefinitely. -
You can customize advanced settings in the DATA file. This file is generated only after your first login and remains there indefinitely.
-
You will see a
ClipCascade.lockfile while the program is running. This file prevents the user from opening multiple instances of ClipCascade.
- You can configure advanced settings on the login page by clicking Enable Extra Config.
- The main options include:
- Store Password Locally: Enable this option if you are frequently getting logged out. The app stores the session cookie for an extended period, but due to the variety of devices used worldwide, exceptions may occur. This option can be very useful.
- Maximum Clipboard Size Local Limit: If the app crashes or stops unexpectedly, it means it received a clipboard size greater than the platform's maximum limit. You can specify a local size limit by typing in the size in bytes (e.g., 512 KiB = 524288 bytes) to test different limits that work for your device. This local limit is in addition to the server-specified limit, ensuring smoother operation without crashes.
- Run on System Startup: Enable this option to allow the app to automatically start on system reboot. By default, this option is disabled. If you are using the ADB workaround, keep this option disabled to avoid issues with the READ_LOGS permission popup being dismissed, which prevents clipboard monitoring in the background.
- The main options include:
When encryption is enabled, the clipboard data is encrypted on client devices. The server does not store this key, ensuring end-to-end encryption. The encryption password is generated using the user’s password, a salt, and the number of rounds, allowing you to control the salt and number of rounds used. This process creates a unique hashed password based on the specified salt and number of rounds.
However, it is crucial to use the same salt and number of rounds across all client devices. The default number of hash rounds is set to 664,937, referred to as hash_rounds, while the default salt is set to empty, referred to as salt.
In the desktop application, you can find these fields in the DATA file located in the software's directory. On mobile devices, you can adjust these settings on the login page under extra config.
Before making any changes, ensure you log out and exit the application. After editing the hash_rounds or salt fields, log back in for the changes to take effect.
Here is a screenshot showing how to set up a reverse proxy using Cloudflare Tunnels. You can apply a similar approach with other providers as well.
- Login: Use your credentials to log into ClipCascade.
- Sync: Copy any text or content to your clipboard, and it will automatically sync across your connected devices.
- Monitor: Open the web-based monitoring page to see your clipboard history in real-time.
Contributions are always welcome! Whether it's a feature request or a pull request, your input helps make ClipCascade even better.
ClipCascade is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for more details.
Here are some planned features and improvements for future releases of ClipCascade:
🗳️ Poll for Prioritization: Cast your vote to prioritize features here.
- iOS Support: Develop and Release a version of ClipCascade for iOS.
- Multiuser Support: Implement multiuser functionality for a single instance, allowing multiple users to sync clipboards independently. (For now, create separate instances for each user.)
- OIDC/OAuth Authentication: Integrate OpenID Connect (OIDC) and OAuth authentication for user login and management.
- Clipboard Data Storage: Implement secure storage for clipboard data to store and access it later.
- Image and File Support: Enable clipboard syncing for images and files, in addition to text data.
If you have any issues or questions, feel free to open an issue on GitHub, start a discussion, or reach out to me via email.