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	Android	Linux

🪟 Desktop (Windows)	📱 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 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.

To host ClipCascade on your server, use Docker with the following steps:

1. Create a docker-compose.yml file with the following content:

   version: '3.8'
   
   services:
     clipcascade:
       image: sathvikrao/clipcascade:0.1.0    #amd64
       # image: sathvikrao/clipcascade:0.1.0-multi-arch     #amd64, arm32v7, arm64v8, ppc64le, s390x
       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)

2. Run the Docker container using Docker Compose:

   docker-compose up -d
   

3. Access the web-based monitoring page at http://localhost:8080.

Note: set up a reverse proxy, see here

To host the ClipCascade server on any operating system that supports Java 17 or higher, follow these steps:

1. Download the JAR File
   Copy the ClipCascade-0.0.1-SNAPSHOT.jar from the release page.

2. Set Environment Variables
   Set the following environment variables in your OS:

   Variable	Value
   CC_USERNAME	your-user-name
   CC_PASSWORD	your-password
   CC_MAX_MESSAGE_SIZE	1

3. Run the Server
   Execute the following command in your terminal:

   java -jar ClipCascade-0.0.1-SNAPSHOT.jar
   

4. Access the Server
   You can access the ClipCascade server at http://localhost:8080.

   Note: set up a reverse proxy, see here

To install the Windows desktop application, download the latest version from the Releases page.

1. Download the installer from the Releases page.
2. 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.
3. 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 /clipsocket for the WebSocket connection (e.g., ws://<server_ip>:<server_port>/clipsocket).
   • If encryption is enabled, please ensure it is enabled on all devices.

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!

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 mobile application on your Android device, download the latest APK from the Releases page.

1. Download the APK from the Releases page.
2. Enable installation from unknown sources in your device settings, if prompted.
3. Install the APK by following the prompts on your device.
4. 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 /clipsocket for the WebSocket connection (e.g., ws://<server_ip>:<server_port>/clipsocket).
   • If encryption is enabled, please ensure it is enabled on all devices.

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.

1. Enable the READ_LOGS permission:

   adb -d shell pm grant com.clipcascade android.permission.READ_LOGS

2. Allow "Drawing over other apps": 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

3. 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

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

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

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 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.

• 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.

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.

1. Login: Use your credentials to log into ClipCascade.
2. Sync: Copy any text or content to your clipboard, and it will automatically sync across your connected devices.
3. Monitor: Open the web-based monitoring page to see your clipboard history in real-time.

Contributions are welcome! Whether it's a feature request or a pull request, your input helps improve ClipCascade.

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:

• Apple macOS and iOS Support: Develop and release versions of ClipCascade for macOS and iOS to enhance cross-platform accessibility.
• Windows Publishing: Publish the Windows application to improve accessibility.
• Android on Play Store: Release the Android application on the Google Play Store for easier installation and updates.

If you encounter any issues or have questions, feel free to open an issue on GitHub or contact me via email.