gem-hunter
Language: Python
ClipCascade is a lightweight utility that automatically syncs the clipboard across devices, no key press required.
ClipCascade is a lightweight, open-source utility that automatically syncs your clipboard across multiple devices—no manual input required. It ensures seamless sharing with robust end-to-end encryption, providing a secure and reliable clipboard experience across workstations.
No Server? No Problem! Instantly sync your clipboard using the Live Community Server at clipcascade.sathvik.dev—no setup needed. Just create an account and start sharing your clipboard across devices in seconds!
| Docker | Windows | macOS | Android | Linux |
|---|---|---|---|---|
|
|
|
|
|
|
|
|
| 🪟 Desktop (Windows) | 🍏 Desktop (macOS) | 🤖📱 Mobile (Android) | 🐧🖱️ Desktop (Linux_GUI) | 🐧⌨️ Desktop (Linux_CLI) |
|---|---|---|---|---|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
| Type | Windows | MacOS | Linux GUI | Linux CLI | Android |
|---|---|---|---|---|---|
| Text | ✔ | ✔ | ✔ | ✔ | ✔ |
| Image | ✔ | ✔ | ✔ | ✔ | ✔ |
| Files | ✔ | ✔ | ✔ | ✔ | ✔ |
To deploy the ClipCascade server on any operating system that supports Java 21 or later, follow the steps outlined below.
Download the Server JAR File
Obtain the latest release of ClipCascade-Server-JRE_21.jar from the release page.
Configure Environment Variables (Optional)
The ClipCascade server supports various environment variables for customization. None of these variables are mandatory, but they can be configured as needed.
For a comprehensive list of available environment variables, refer to the Advanced Details section.
| Variable | Description | Default Value | Example |
|---|---|---|---|
CC_MAX_MESSAGE_SIZE_IN_MiB |
Defines the maximum allowed message size in MiB. Ignored if CC_P2P_ENABLED is set to true. |
1 |
3 |
CC_ALLOWED_ORIGINS |
Specifies the allowed CORS origins for secure cross-origin access. | * |
https://clipcascade.example.com |
CC_P2P_ENABLED |
Enables or disables peer-to-peer mode. When enabled, CC_MAX_MESSAGE_SIZE_IN_MiB is ignored. |
false |
true |
CC_SIGNUP_ENABLED |
Allows or restricts user self-registration. | false |
false |
CC_PORT |
Specifies the port on which the server listens for incoming connections. | 8080 |
1234 |
Start the Server
Run the following command in the terminal to launch the ClipCascade server:
java -jar ClipCascade-Server-JRE_21.jar
Access the Server
Once the server is running, you can access it via:
http://localhost:8080
adminadmin123Important: It is strongly recommended to change the default credentials immediately after the initial login.
For guidance on setting up a reverse proxy, refer to the Reverse Proxy Setup section.
For users who prefer a one-liner, you can deploy ClipCascade instantly using:
docker run -d --name clipcascade -p 8080:8080 -e CC_MAX_MESSAGE_SIZE_IN_MiB=1 -v ./cc_users:/database sathvikrao/clipcascadeTo host ClipCascade on your server using Docker, follow these steps:
Create a docker-compose.yml File
Create a docker-compose.yml file with the following content, or download it from the release page:
services: clipcascade: image: sathvikrao/clipcascade:latest ports: - "8080:8080" # Expose the ClipCascade server on port 8080 restart: always # Automatically restart the container if it stops volumes: - ./cc_users:/database # Persistent storage for user data environment: - CC_MAX_MESSAGE_SIZE_IN_MiB=1 # Maximum message size in MiB (ignored if P2P mode is enabled) - CC_P2P_ENABLED=false # Enables or disables peer-to-peer(P2P) mode # - CC_ALLOWED_ORIGINS=https://clipcascade.example.com # Defines allowed CORS origins for security # - CC_SIGNUP_ENABLED=false # Enables or disables user self-registration
For additional .yml configuration files, visit ClipCascade Server Docker Configuration.
Deploy the Docker Container
Run the Docker container using Docker Compose:
docker-compose up -d
Access the Server
Once the server is running, you can access it via:
http://localhost:8080
adminadmin123Important: It is strongly recommended to change the default credentials immediately after the initial login.
For guidance on setting up a reverse proxy, refer to the Reverse Proxy Setup section.
To install the ClipCascade Windows desktop application, follow these steps:
.msi installer and follow the on-screen instructions, and select the default installation path specified by the installer.If the server is running in P2P mode, you will see a Windows security prompt asking, "Do you want to allow public and private networks to access this app?"
This is because each client device acts as a peer in the network, requiring direct communication.
Click Allow to enable clipboard data syncing across your devices without the help of a server. The server is needed only for signaling and authentication.
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.
To build your own desktop executable from source (ClipCascade_Desktop/src):
pip3 install pyinstaller pip3 install -r requirements_win.txt python3 -m PyInstaller ClipCascade_win.spec
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 ClipCascade macOS desktop application, follow these steps:
Download the Application
ClipCascade-Apple_macOS.ARM_M-Series.zip.ClipCascade-Apple_macOS.Intel-Series.zip.Extract the Archive
.zip file to extract its contents.Locate the Application
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
Configure the application
Network Access Prompt (P2P Mode)
If the server is running in P2P mode, you will see a macOS security prompt asking, "Allow "ClipCascade" to find devices on local networks?"
This is because each client device acts as a peer in the network, requiring direct communication.
Click Allow to enable clipboard data syncing across your devices without the help of a server. The server is needed only for signaling and authentication.
Access the App from the Menu Bar
Enable Auto-Startup:
Right-click the ClipCascade icon in the dock (bottom of the screen).
Select Options and then check Open at Login.
Alternatively, open Settings → General → Login Items & Extensions, then add ClipCascade manually.
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 build your own desktop executable from source (ClipCascade_Desktop/src):
pip3 install certifi pyinstaller pip3 install --no-cache-dir -r requirements_mac.txt python3 -m PyInstaller ClipCascade_macos.spec --clean
To install the ClipCascade mobile application on your Android device, follow these steps:
ClipCascade supports automatic clipboard monitoring for both rooted and non-rooted devices. To activate this feature, execute the following ADB commands.
Before proceeding, make sure ADB is installed on your system. Follow the instructions here to install ADB on Windows, macOS, or Linux.
Grant the READ_LOGS permission:
adb -d shell pm grant com.clipcascade android.permission.READ_LOGS
Enable "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 allowKill 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 connected devices 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, 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: On startup, ClipCascade reads a handful of standard environment variables your desktop session already sets—such as
XDG_SESSION_TYPE,WAYLAND_DISPLAY, andDISPLAY—so it knows which display and clipboard APIs to use (the same kind of information any graphical app needs locally). From those values it classifies the environment as X11, XWayland (a Wayland session that also exposes an X11 socket), Hyprland, native Wayland, or unknown. That classification picks both the default clipboard integration (X11-style versus Wayland-style tools) and the default user interface (GTK tray / GUI versus terminal-based CLI). X11, XWayland, and unknown default to the X11-style clipboard path and GUI; native Wayland and Hyprland default to the Wayland-style clipboard path and CLI. You can override defaults with--guiand--xmode(see below)—for example,--gui trueon Wayland still uses the Wayland clipboard path unless you also change--xmode.
sudo apt update
sudo apt install -y python3 python3-pip python3-gi xclip wl-clipboard dunst
sudo dnf check-update
sudo dnf install -y python3 python3-pip python3-gobject xclip wl-clipboard dunst
sudo pacman -Syu --noconfirm python python-pip python-gobject xclip wl-clipboard dunst xdg-utils
sudo apt install -y python3-gi-cairo gir1.2-gtk-3.0 gir1.2-gdk-3.0
sudo dnf install -y libappindicator-gtk3
sudo pacman -S --noconfirm python-gobject gtk3
Install the GNOME tray support extension.
sudo pip3 install -r requirements.txt
sudo pip 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-pyfiglet python3-bs4 python3-plyer python3-aiortc
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 python3-aiortc
sudo pacman -S --noconfirm python-xxhash python-pyperclip python-requests python-websocket-client python-pycryptodome tk python-pystray python-pyfiglet python-beautifulsoup4 python-plyer python-aiortc
error: target not found: python-plyer, install via yay -S --noconfirm python-plyererror: target not found: python-aiortc, install via yay -S --noconfirm python-aiortcsudo apt install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libavfilter-dev libswscale-dev libswresample-dev pkg-config
sudo dnf install -y ffmpeg ffmpeg-devel
sudo pacman -S --noconfirm ffmpeg
Start ClipCascade by running (use sudo if needed):
python3 main.py
Linux supports optional launch arguments to manually tune behavior when needed:
--gui <true|false>: force GUI (tray / GTK login) with true, or terminal CLI with false, independent of the auto-selected default.--xmode <true|false>: force X11 / XWayland-style clipboard handling (xclip, GTK clipboard when applicable) with true, or Wayland-style handling (wl-clipboard) with false.--polling <seconds>: override clipboard polling interval (must be a positive number).When flags are omitted, display-server detection sets the default --xmode behavior, and the default GUI vs CLI follows that same classification (GUI for X11, XWayland, and unknown; CLI for native Wayland and Hyprland). Use --gui / --xmode if your session variables do not match how you want the app to run.
Examples:
python3 main.py --gui true python3 main.py --gui false --xmode false --polling 3 python3 main.py --polling 1.5
If these flags are not provided, ClipCascade automatically detects your environment and selects the most suitable clipboard path and interface.
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 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
sudo pacman -S --noconfirm tk
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
sudo apt install dbus-x11
sudo dnf install dbus-x11
sudo pacman -S --noconfirm dbus
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 &
To ensure ClipCascade starts automatically when your system boots, modify the file paths as necessary and add the appropriate command to your startup script.
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 &
cd /path/to/clipcascade/src/ && python3 main.py
If root privileges are required, use:
cd /path/to/clipcascade/src/ && sudo python3 main.py
Change the default admin credentials immediately after logging in to prevent unauthorized access.
adminadmin123/healthOK with a status code 200 when the server is up and running.The server features a built-in update checker, prominently displayed on the homepage, keeping you informed about the latest enhancements and security fixes. This ensures your server stays up to date.
| Environment Variable | Extended Description | Default Value |
|---|---|---|
| CC_MAX_MESSAGE_SIZE_IN_MiB |
Defines the maximum message size (in MiB) that the server can handle.
Note: - Android typically supports larger clipboard sizes for images and files but limits text to ~1 MiB. - Desktop supports larger clipboard sizes across text, images, and files. Additional Notes: - Clients can set their own limits via **Show advanced settings** on the login page. - If CC_P2P_ENABLED is true, this setting is ignored.
|
1 |
| CC_MAX_MESSAGE_SIZE_IN_BYTES |
Provides finer control over message size by specifying a limit in bytes.
Note: If set above zero, it overrides CC_MAX_MESSAGE_SIZE_IN_MiB.Ignored if CC_P2P_ENABLED is true.
|
0 |
| CC_P2P_ENABLED |
Toggles the Peer-to-Peer (P2P) feature, allowing direct device-to-device communication.
Advantages: - Reduces server load. - Removes size restrictions, enabling unlimited data transfer. Important Notes: - If enabled, CC_MAX_MESSAGE_SIZE_IN_MiB and CC_MAX_MESSAGE_SIZE_IN_BYTES are ignored.- Some network configurations may not support P2P. |
false |
| CC_P2P_STUN_URL |
Defines the STUN server URL used for P2P communication, helping devices discover each other across NAT.
Note: Required when CC_P2P_ENABLED is true.You can use a public STUN server or host your own. |
stun:stun.l.google.com:19302 |
| CC_ALLOWED_ORIGINS |
Specifies which domain is permitted to access the WebSocket server (CORS policy).
Security Note: - Leaving this unset allows all origins (not recommended for security-sensitive deployments). - To restrict access, specify your domain (e.g., https://clipcascade.example.com).
|
* |
| CC_SIGNUP_ENABLED |
Determines whether new users can sign up.
Default: false (public signups are disabled).
|
false |
| CC_MAX_USER_ACCOUNTS |
Defines the maximum number of user accounts allowed on the server.
Note: -1 means no limit.
|
-1 |
| CC_ACCOUNT_PURGE_TIMEOUT_SECONDS |
Specifies the duration (in seconds) after which inactive accounts are deleted.
Example: 63115200 (equivalent to 2 years).Note: -1 disables automatic purging.
|
-1 |
| CC_PORT |
Defines the internal port where the ClipCascade server listens for connections.
Default: 8080, but can be changed if necessary. |
8080 |
| CC_SESSION_TIMEOUT |
Specifies the duration before user sessions expire, using minute-based formatting ([number]m).
Default: 525960m (~1 year).
Sessions are lost on server restart unless CC_SESSION_PERSISTENCE_ENABLED is enabled.
|
525960m |
| CC_MAX_UNIQUE_IP_ATTEMPTS | Sets the maximum number of failed login attempts from different IP addresses before an account is blocked. | 15 |
| CC_MAX_ATTEMPTS_PER_IP | Limits the number of failed login attempts allowed per IP before temporarily blocking that IP. | 30 |
| CC_LOCK_TIMEOUT_SECONDS | Defines the initial lockout duration (in seconds) after too many failed login attempts. | 60 |
| CC_LOCK_TIMEOUT_SCALING_FACTOR |
Determines how the lockout time increases with each consecutive failed attempt.
Examples: - Factor 1: 60, 120, 180… - Factor 2: 120, 240, 360… - Factor 3: 180, 360, 540… |
2 |
| CC_BFA_CACHE_ENABLED | Controls whether brute force attack (BFA) data is cached in memory and disk. | false |
| CC_BFA_TRACKER_CACHE_MAX_JVM_ENTRIES |
Specifies the maximum number of entries in the BFA tracker cache, stored in JVM memory.
Note: Only used if CC_BFA_CACHE_ENABLED is true.
|
50 |
| CC_BFA_TRACKER_CACHE_RAM_PERCENTAGE |
Defines the percentage of the BFA tracker cache allocated to off-heap RAM.
Note: Only used if CC_BFA_CACHE_ENABLED is true.
|
0 |
| CC_BFA_TRACKER_CACHE_DISK_PERCENTAGE |
Defines the percentage of the BFA tracker cache allocated to disk.
Note: Only used if CC_BFA_CACHE_ENABLED is true.
|
40 |
| CC_SERVER_DB_USERNAME | Specifies the username for the database connection. | clipcascade |
| CC_SERVER_DB_PASSWORD |
Defines the password used for encrypting the user database.
Note: - (H2) Change the default password to secure values in the format <file password> <user password> before the first server start, especially when CC_SESSION_PERSISTENCE_ENABLED is enabled, since login sessions are stored in the database.- Keep the same value across restarts, upgrades, and migrations when reusing the database. Changing this variable alone does not update the existing database's password. |
QjuGlhE3uwylBBANMkX1 o2MdEoFgbU5XkFvTftky |
| CC_SERVER_DB_URL |
Defines the JDBC URL used to connect to the database.
Examples: - PostgreSQL: jdbc:postgresql://localhost:5432/clipcascade
|
jdbc:h2:file:./database/clipcascade;CIPHER=AES;MODE=PostgreSQL |
| CC_SERVER_DB_DRIVER |
Specifies the JDBC driver class used by the database connection.
Example: org.postgresql.Driver for PostgreSQL.
|
org.h2.Driver |
| CC_SERVER_DB_HIBERNATE_DIALECT |
Sets the Hibernate dialect for the chosen database.
Example: org.hibernate.dialect.PostgreSQLDialect for PostgreSQL.
|
org.hibernate.dialect.H2Dialect |
| CC_SERVER_LOGGING_LEVEL | Sets the logging verbosity level (TRACE, DEBUG, INFO). | INFO |
| CC_SERVER_LOG_HISTORY_MAX_DAYS | Specifies how many days of logs to retain before they are rotated or removed. | 30 |
| CC_SERVER_LOG_MAX_CAPACITY | Defines the maximum total size of logs to keep before older files are purged. | 1GB |
| CC_LOG_BRUTE_FORCE_TRACKER_ENABLED |
Enables detailed logging of each login attempt in the Brute Force Attack (BFA) tracker.
Useful for diagnosing repeated login failures. |
false |
| CC_EXTERNAL_BROKER_ENABLED | Determines whether an external STOMP broker is used for message handling. | false |
| CC_BROKER_HOST |
Specifies the STOMP broker host for external message handling.
Note: Only used if CC_EXTERNAL_BROKER_ENABLED is true.
|
localhost |
| CC_BROKER_PORT |
Specifies the STOMP broker port for external message handling.
Note: Only used if CC_EXTERNAL_BROKER_ENABLED is true.
|
61613 |
| CC_BROKER_USERNAME |
Defines the STOMP broker username for external message handling.
Note: Only used if CC_EXTERNAL_BROKER_ENABLED is true.
|
admin |
| CC_BROKER_PASSWORD |
Defines the STOMP broker password for external message handling.
Note: Only used if CC_EXTERNAL_BROKER_ENABLED is true.
|
admin |
| CC_MAX_WS_GLOBAL_CONNECTIONS |
Maximum number of global WebSocket connections allowed.
Supported Mode: Only applies when CC_P2P_ENABLED is true.
Note: - This value represents the total number of active WebSocket connections allowed across all users. - -1 means unlimited.
|
-1 |
| CC_MAX_WS_CONNECTIONS_PER_USER |
Maximum number of WebSocket connections allowed per user.
Supported Mode: Only applies when CC_P2P_ENABLED is true.
Note: - This value limits how many simultaneous WebSocket connections a single user can have. - -1 means unlimited.
|
-1 |
| CC_SESSION_PERSISTENCE_ENABLED |
Keeps login sessions across server restarts in the existing H2 or PostgreSQL database. Requires persistent database storage (the /database volume for Docker's default H2 setup).
Se | |
| ||
|
 |  |
 |  |
 |  |
| |
| |
| |
| |
| |
| |
|
