ClipCascade

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

📸 Screenshots

🪟 Desktop (Windows)	🍏 Desktop (macOS)	🤖📱 Mobile (Android)	🐧🖱️ Desktop (Linux_GUI)	🐧⌨️ Desktop (Linux_CLI)

✨ Features

• 🔒 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.
• 👥 Multi-User Support: Sync clipboard data across multiple user accounts, allowing each user to manage their clipboard independently while still enjoying seamless cross-device synchronization.

Type	Windows	MacOS	Linux GUI	Linux CLI	Android
Text	✔	✔	✔	✔	✔
Image	✔	✔	✔	✔	✔
Files	✔	✔	✔	✔	✔

📥 Installation

🦈 Self-Hosted Docker Server:

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'
   # Default admin credentials: username - admin, password - admin123
   
   services:
     clipcascade:
       image: sathvikrao/clipcascade:latest
       ports:
         - "8080:8080"
       restart: always
       environment:
         # To learn more about environment variables, check the Advanced Details section in the GitHub README.
         - CC_MAX_MESSAGE_SIZE_IN_MiB=1
         # - CC_ALLOWED_ORIGINS=https://clipcascade.example.com
         # - CC_SERVER_DB_PASSWORD=QjuGlhE3uwylBBANMkX1 o2MdEoFgbU5XkFvTftky
         # - CC_SERVER_LOGGING_LEVEL=DEBUG
       volumes:
         - ./cc_users:/database

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

Check Advanced Details

🦾 Self-Hosted Server Bare Metal:

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-Server-JRE_17.jar from the release page.

2. Set Environment Variables

   Set the following environment variables in your OS (none of them are mandatory). To learn more about environment variables, check here.

   Variable	Value
   CC_MAX_MESSAGE_SIZE_IN_MiB	1
   CC_ALLOWED_ORIGINS	https://clipcascade.example.com
   CC_SERVER_DB_PASSWORD	QjuGlhE3uwylBBANMkX1 o2MdEoFgbU5XkFvTftky
   CC_SERVER_LOGGING_LEVEL	DEBUG

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

   java -jar ClipCascade-Server-JRE_17.jar

4. Access the Server
   You can access the ClipCascade server at http://localhost:8080. The default username is admin and the default password is admin123.

   Note: set up a reverse proxy, see here

Check Advanced Details

🪟 Windows Desktop Application:

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, enter the server's IP address, port number, or domain name.
   • If encryption is enabled, please ensure it is enabled on all devices.

Check Advanced Details

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.

🍏 macOS Desktop Application:

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

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

2. Extract the contents:

   • Double-click on the .zip file to extract the files.

3. Navigate to the extracted folder.

4. You will find the ClipCascade application inside. You can move this application to any location you prefer on your system.

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

       

6. Wait for the app to launch: When you open the application, macOS will scan the application. This may take 10–30 seconds.

7. Connect to the server:

   • When prompted, enter the server's IP address, port number, or domain name.
   • If encryption is enabled, please ensure it is enabled on all devices.

8. Once logged in, the application will run in the menu bar with a clipboard icon at the top of your screen.

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

     

Check Advanced Details

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.

🤖📱 Android Mobile Application:

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, enter the server's IP address, port number, or domain name.
   • If encryption is enabled, please ensure it is enabled on all devices.

Check Advanced Details

Android Automatic Clipboard Monitoring Setup:

To enable automatic clipboard monitoring on both rooted and non-rooted devices, execute the following three ADB commands.

Install ADB

Before proceeding, make sure ADB is installed on your system. Follow the instructions here to install ADB on Windows, macOS, or Linux.

ADB Commands

1. Enable the READ_LOGS permission:

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

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

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

🐧🖱️ Linux Desktop Application (GUI) / 🐧⌨️ Linux Terminal-Based Application (CLI):

This guide provides step-by-step instructions to install ClipCascade on Debian/Ubuntu, Fedora, and Arch-based systems. While the commands are specifically tailored for these distributions, you can adapt the process for other Linux distributions with minor modifications. The Linux code is available on the Releases page as ClipCascade_Linux.zip. Once downloaded, navigate to the ClipCascade/ folder containing main.py, and open a terminal in that directory.

Note: Linux systems use different display servers, primarily X11 and Wayland. Wayland can also include XWayland, which supports X sessions. The program automatically detects the display server and selects the appropriate interface, either GUI or CLI, based on the environment.

Step 1: Check for updates and install required packages

Debian/Ubuntu:

sudo apt update
sudo apt install -y python3 python3-pip python3-gi xclip wl-clipboard dunst

Fedora:

sudo dnf check-update
sudo dnf install -y python3 python3-pip python3-gobject xclip wl-clipboard dunst

Arch:

sudo pacman -Syu --noconfirm python python-pip python-gobject xclip wl-clipboard dunst xdg-utils

Step 2: Install GTK 3.0 for clipboard monitoring and GUI support

Debian/Ubuntu:

sudo apt install -y python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdk-3.0

Fedora:

sudo dnf install -y libappindicator-gtk3

Arch:

sudo pacman -S --noconfirm python-gobject gtk3

Step 3: Install GNOME tray support extension (if tray icon is unavailable)

Install the GNOME tray support extension.

Step 4: Install Python Dependencies

Debian/Ubuntu/Fedora:

sudo pip3 install -r requirements.txt

Arch:

sudo pip install -r requirements.txt

Step 4.1: Fix externally-managed-environment Error (if applicable)

If you encounter the error: externally-managed-environment, install the required Python packages manually.

Debian/Ubuntu:

sudo apt install -y python3-xxhash python3-pyperclip python3-requests python3-websocket python3-pycryptodome python3-tk python3-pystray python3-pyfiglet python3-bs4 python3-plyer

Fedora:

sudo dnf install -y python3-xxhash python3-pyperclip python3-requests python3-websocket-client python3-pycryptodomex python3-tkinter python3-pystray python3-pyfiglet python3-beautifulsoup4 python3-plyer

Arch:

sudo pacman -S --noconfirm python-xxhash python-pyperclip python-requests python-websocket-client python-pycryptodome tk python-pystray python-pyfiglet python-beautifulsoup4 python-plyer

If you encounter the error: target not found: python-plyer, install via yay -S --noconfirm python-plyer

Step 5: Run the Application

Start ClipCascade by running (use sudo if needed):

• When prompted, enter the server's IP address, port number, or domain name.
• If encryption is enabled, please ensure it is enabled on all devices.

python3 main.py

Step 5.1: Fix 'No module named Crypto' Error (if applicable)

If you encounter the No module named 'Crypto' error, create a symbolic link for the Cryptodome library: see more

Debian/Ubuntu:

sudo ln -s /usr/lib/python3/dist-packages/Cryptodome /usr/lib/python3/dist-packages/Crypto

Fedora:

sudo ln -s /usr/lib/python3/site-packages/Cryptodome /usr/lib/python3/site-packages/Crypto

Arch:

sudo ln -s /usr/lib/python3.*/site-packages/Cryptodome /usr/lib/python3.*/site-packages/Crypto

Step 5.2: Fix 'ModuleNotFoundError: No module named tkinter' Error (if applicable)

If you encounter the No module named 'tkinter' error:

Debian/Ubuntu:

sudo apt install -y python3-tkinter

Fedora:

sudo dnf install -y python3-tkinter

Arch:

sudo pacman -S --noconfirm tk

Step 5.3: Fix 'gtk_widget_get_scale_factor: assertion 'GTK_IS_WIDGET (widget)' failed' Error (if applicable)

This error occurs due to a missing tray icon extension in GNOME. To resolve it, you can install the extension from here

Step 5.4: Fix 'g-exec-error-quark' Error (if applicable)

Debian/Ubuntu:

sudo apt install dbus-x11

Fedora:

sudo dnf install dbus-x11

Arch:

sudo pacman -S --noconfirm dbus

Step 6: Run the Application in the Background (if needed)

To run ClipCascade as a background process (if the GUI setup is functional), use the following command:

nohup python3 main.py &> /dev/null &

If root privileges are required, use:

sudo nohup python3 main.py &> /dev/null &

Step 7: Add ClipCascade to Startup Script (if needed)

To ensure ClipCascade starts automatically when your system boots, modify the file paths as necessary and add the appropriate command to your startup script.

Example:

GUI

cd /path/to/clipcascade/src/ && nohup python3 main.py &> /dev/null &

If root privileges are required, use:

cd /path/to/clipcascade/src/ && sudo nohup python3 main.py &> /dev/null &

CLI

cd /path/to/clipcascade/src/ && python3 main.py

If root privileges are required, use:

cd /path/to/clipcascade/src/ && sudo python3 main.py

Check Advanced Details

⚙️ Advanced Details

🗄️ Server Configuration

Default Admin Credentials:

• Username: admin
• Password: admin123

Supported Environment Variables:

1. CC_MAX_MESSAGE_SIZE_IN_MiB

   • Purpose: Sets the maximum message size (in MiB) that the server can handle.
   • Platform-specific behavior:
     • Android: Supports larger clipboard sizes for images and files. However, text is typically limited to ~1 MiB.
     • Desktop: Supports larger clipboard sizes for text, images, and files.
   • Default Value: 1 MiB
   • Usage: Adjust this value based on your use case and platform requirements.
   • Example: CC_MAX_MESSAGE_SIZE_IN_MiB=3

   Note: Individual clients can configure their own limits via the "Extra Config" option on the login page.

2. CC_ALLOWED_ORIGINS

   • Purpose: Specifies which domains are permitted to connect to the WebSocket (CORS policy).
   • Default Behavior: If not set, all origins are allowed by default, which may pose security risks.
   • Usage: Replace the URL with your ClipCascade server's domain.
   • Example: CC_ALLOWED_ORIGINS=https://clipcascade.example.com

3. CC_SERVER_DB_PASSWORD

   • Purpose: Encrypts the user database with a secure password.
   • Default Value: QjuGlhE3uwylBBANMkX1 o2MdEoFgbU5XkFvTftky
   • Usage: Replace <file password> and <user password> with strong, secure values. Ensure the same password is used when migrating the database.
   • Example: CC_SERVER_DB_PASSWORD=QjuGlhE3uwylBBANMkX1 o2MdEoFgbU5XkFvTftky

4. CC_SERVER_LOGGING_LEVEL

   • Purpose: Configures the server's logging level for diagnostics and troubleshooting.
   • Available Levels:
     • TRACE (most detailed)
     • DEBUG
     • INFO (default)
     • WARN
     • ERROR
     • FATAL
     • OFF (disables logging)
   • Example: CC_SERVER_LOGGING_LEVEL=DEBUG

Health Check Endpoint:

• Purpose: Verifies if the server is running and operational.
• Endpoint: /health
• Response: Returns OK with a status code 200 when the server is up and running.

🖥️📱 Client Apps

• Logs (clipcascade_log.log) are stored in the installation directory on Windows and Linux, and in <current user>/Library/Application Support/ClipCascade/ on macOS. These logs allow you to review application activity and are automatically reset each time the application is reopened, preventing indefinite growth.
• The DATA file stores settings and user details, enabling the app to retain this information across both restarts and updates.
• On Linux and macOS, a ClipCascade.lock file is created while the program is running. This file ensures that only a single instance of ClipCascade can be opened at a time.

Extra Config/Advanced Settings (Desktop/Mobile):

• Maximum Clipboard Size Local Limit (in bytes): If the app crashes or stops unexpectedly, it may be due to receiving clipboard content exceeding the platform's maximum size limit. You can set a local size limit by specifying a value in bytes (e.g., 512 KiB = 524288 bytes) to test different thresholds suitable for your device. This local limit works alongside the server-specified limit to ensure smoother operation without crashes. For example, on Android (particularly on the Pixel 6a as of 2024), the platform limit(for text) is typically less than 1 MiB. Since the server limit cannot go below 1 MiB, setting the local limit to around 900,000 bytes on the Pixel 6a can help prevent crashes.

• Store Password Locally (not recommended): Enable this option if you frequently encounter session logouts. While the app stores session cookies for an extended period, a server restart may prompt a re-login. If re-entering the password becomes tedious, you can use this option to store your password locally for convenience.

  Note: This option will only work if encryption is disabled, as encryption requires the raw password to generate a password hash, not the stored hashed password.

• Enable Image Sharing and Enable File Sharing: Enabling these options allows the app to send images or files. However, the app will continue to receive images and files even if these options are disabled.

• Enable Notification: Turn on this option to receive notifications about WebSocket disconnections and reconnections.

• Enable Encryption (recommended): Enabling this option activates end-to-end encryption for clipboard data. This ensures that all clipboard content is encrypted before leaving your device. Refer to the section below on E2E encryption for detailed instructions on how it works and how to configure the salt and hash rounds.

  Desktop (Specific):

  • Default File Download Location: When this path is set, the app will save files directly to the specified location without prompting the user each time the "Download Files" button is clicked.

  Android (Specific):

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

  • Enable Periodic Checks: Enabling this option performs periodic checks to ensure clipboard monitoring and the foreground service are running. It verifies the service status when monitoring starts and then checks every 15 minutes in the background. If the service is not running, a notification is displayed. Clicking the notification will restart the service.

    

🔒 End-to-End Encryption Configuration for Clipboard Data

When encryption is enabled, clipboard data is encrypted directly on the client devices, ensuring true end-to-end encryption. The server does not store the encryption key, offering maximum security for your data.

Enabling the encryption option is all that's needed to activate encryption by default. However, advanced users have the option to further customize the encryption process by adjusting the following parameters:

• Salt: An optional string used as an additional input in the hashing process. For example, you could use a unique string like "myCustomSalt123" to enhance encryption security.

• Hash Rounds: An integer that specifies the number of hashing iterations. Increasing the hash rounds strengthens encryption by making it more computationally demanding. You can increase the default value of 664,937 to a higher number, such as 1,000,000, to boost security.

It is crucial to ensure the same salt and hash rounds are used across all client devices to maintain compatibility.

You can adjust these settings in the Extra Config section on the login page for users who require enhanced encryption options.

📋 Clipboard Functioning

• Text and Images: These are directly copied to the clipboard, enabling seamless sharing across devices.

• Files: When files are received, a notification icon appears in the system tray (on desktop platforms). Since the clipboard does not store files, only their file paths are retained.

  Desktop	Mobile

• Clipboard Monitoring:

  Platform	Implementation Details
  Windows	Uses win32gui, win32api, win32con, and win32clipboard to capture clipboard changes in an event-driven manner.
  macOS	Utilizes the pasteboard to monitor the clipboard with polling every 0.3 seconds. Instead of checking clipboard content directly, it compares a counter to detect changes efficiently.
  Linux (X11)	Employs Gtk.Clipboard to capture clipboard changes in an event-driven manner, running in GUI mode.
  Linux (XWayland, Unknown)	Switches between Gtk.Clipboard (event-based) or x-clip (polling every 0.3 seconds) depending on permissions (requires sudo for Gtk.Clipboard). Both operate in GUI mode.
  Linux (Wayland, Hyprland)	Uses wl-clipboard with polling every 1 seconds in CLI mode. The delay accounts for Wayland's requirement to focus a window to grab clipboard content, ensuring smoother OS interaction.
  Android	Leverages ClipboardManager to capture clipboard changes in an event-driven manner.

  Type	Send					Receive
  	Windows	MacOS	Linux GUI	Linux CLI	Android	Windows	MacOS	Linux GUI	Linux CLI	Android
  Text	✱	✱	✱	✱	✱ / share	✱	✱	✱	✱	✱
  Image	✱	✱	✱	✱	✱ / share	✱	✱	✱	✱	✱
  Files	✱	✱	✱	✱	share	click	click	click	click	click

⇄ Reverse Proxy Setup

Below is a screenshot demonstrating how to configure a reverse proxy using Cloudflare Tunnels. Similar configurations can be applied with other providers as well.

Note:

For other providers, you may need to configure HTTP to HTTPS redirection manually by adding a permanent redirection rule.

Example: Caddy Configuration

http://clipcascade.sample.com {
	redir https://clipcascade.sample.com{uri} permanent
}

Note:

Additionally, it might be helpful to mention that the server uses WebSockets (ws/wss) for live clipboard broadcasting. In most cases, no extra configuration is needed for WebSockets since they typically rely on an HTTP switching protocol. Most providers will support WebSocket connections out of the box, without requiring additional setup. Example: ws://localhost:8080/clipsocket.

🔧 Usage

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.

🌍 Contributing

Contributions are always welcome! Whether it's a feature request or a pull request, your input helps make ClipCascade even better.

📜 License

ClipCascade is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for more details.

🛠️ TODO

Here are some planned features and improvements for future releases of ClipCascade:

🗳️ Poll for Prioritization: Cast your vote to prioritize features here.

• Clipboard Data Storage: Implement secure storage for clipboard data to store and access it later.
• OIDC/OAuth Authentication: Integrate OpenID Connect (OIDC) and OAuth authentication for user login and management.
• iOS Support: Develop and Release a version of ClipCascade for iOS.

📦 Versioning

ClipCascade uses Semantic Versioning (SemVer) for releases:

• 🔴 Major (X): Incremented for releases that introduce backward incompatible changes.
• 🟠 Minor (Y): Incremented for backward compatible functionality added.
• 🟢 Patch (Z): Incremented for backward compatible bug fixes or minor improvements.

Version Format

X.Y.Z
Where:

• X is the major version.
• Y is the minor version.
• Z is the patch version.

Example versioning:

• 1.0.0: Initial release.
• 1.1.0: Added new features, backward compatible.
• 2.0.0: Major changes, not backward compatible.

💬 Support

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.