ClipShare is a lightweight and cross-platform tool for clipboard sharing. ClipShare enables copying text, files, and images on one device and pasted on another. ClipShare is simple and easy to use while being highly configurable. The ClipShare server runs in the background on your desktop/laptop. Clients can connect to the server and share copied text, files, and images.
| Server | Client |
|---|---|
 Download the server from Releases. |
 Download the client app from apt.izzysoft.de/fdroid/index/apk/com.tw.clipshare. or from GitHub Releases. |
Note: This section is required only for macOS.
ClipShare needs the following libraries to run:
These libraries can be installed using Homebrew with the following command:
brew install libunistring openssl@3 libpng- You can run the server from a terminal or the GUI (if the file manager supports executing programs by double-clicking on it).
- On macOS, if you run the server from the GUI (by double-clicking it on Finder), it may open a terminal window. But you can close this window. The server will continue running in the background.
- When the server starts, it will not display any visible window. Instead, it will run in the background.
- On Linux or macOS, if you start the program from the terminal, it should return immediately unless the
-Dflag (no-daemonize) is used. The server will continue to run in the background. - On Windows, it will show a tray icon unless disabled from the configuration file. You can click on it to stop the server.
- If something goes wrong, it will create a
server_err.logfile. That file will contain what went wrong.
This server listens on the following ports (unless different ports are assigned from the configuration),
4337/TCP- For application traffic (not encrypted)4337/UDP- For network scanning using UDP broadcasts4338/TCP- For application traffic over TLS (encrypted)4339/TCP- For the web server (only if the web server is available)
You may need to allow incoming connections to the above ports for the client to connect to the server.
Note that all TCP ports are for unicast, while 4337/udp is used to receive broadcast. Therefore, the firewall rule that allows 4337/udp should have the broadcast address of the interface as the destination address.
You can find an Android client app in releases. You can also get it from apt.izzysoft.de. The source of the Android client app is available at github.com/thevindu-w/clip_share_client. Or you may develop a client app according to the protocol specification described in the docs/.
- The client and the server devices should be on the same network. You can do that by connecting both devices to the same Wi-Fi network. It is also possible to use one of the devices as a Wi-Fi hotspot and connect the other device to that hotspot.
- If the client supports network scanning, it can easily find the server in the network. Otherwise, enter the server's IPv4 address to the client.
- Now the client can share clipboard data and files and get images from the server.
Note that the server should allow the client through the firewall, as mentioned in the above section.
Note: This section is optional if you prefer manually starting the server over automatically starting on login/reboot.
To install the server to run on startup, use the corresponding installer script for your platform.
Online installer scripts are attached with the releases. They will download the corresponding version during installation. Therefore, they do not require having the compiled binaries along with the installer to run it. However, they require internet access to download the binaries from GitHub during installation. Run the interactive script and follow the instructions to install ClipShare.
Standalone installer scripts are available in the archives (zip for Windows and macOS, and tar.gz for Linux) attached to releases on GitHub. They are also available in the helper_tools/ directory. Standalone installers can run without an internet connection. However, you must have the clip_share (or clip_share.exe on Windows) executable in the current working directory to run the installer. If you download the archive from releases and extract it, you will have the executable along with the installer script. Run the interactive script and follow the instructions to install ClipShare.
Linux and macOS
- Open a terminal in the directory where the
clip_shareexecutable is available (the executable name may have suffixes like_GLIBC*on Linux orarm64orx86_64on macOS). - Run the install script as shown below, and follow the instructions of it.
# on Linux
chmod +x install-linux.sh
./install-linux.sh# on macOS
chmod +x install-mac.sh
./install-mac.shWindows
- Place the
install-windows.batfile and theclip_share.exeexecutable in the same folder. (the executable name may have suffixes) - Double-click on the
install-windows.batinstaller script to run it. It will open a Command Prompt window. Follow the instructions on it to install ClipShare. (If double-clicking did not run the installer, right-click on it and select Run)
Note: This section is optional if you do not need the TLS encrypted mode and the web mode.
The following files should be created, and their paths should be specified in the configuration file clipshare.conf. You may use different file names and paths to store the keys and certificates.
server.pfx- SSL/TLS key and certificate file of the serverca.crt- SSL/TLS certificate of the CA, which signed both the server's and the client's SSL/TLS certificates
You may use the helper scripts keygen.sh or keygen.ps1 in the helper_tools/ directory to generate TLS keys and certificates for both the server and the client. Linux and macOS users can use keygen.sh. Windows users can use keygen.ps1 PowerShell script which doesn't require OpenSSL. Windows users may also use keygen.sh if running in a Bash shell (ex: Git Bash). However, this requires OpenSSL version 3.x or later.
Linux and macOS (Using OpenSSL)
Keep the `clipshare.ext` file in the same directory as the `keygen.sh` script when running the script.# If you download/clone the repository and run the script from the repository root,
helper_tools/keygen.sh# If you download the script separately and run the script from within the same directory,
chmod +x keygen.sh
./keygen.shRefer to the OpenSSL manual for more information on generating keys.
Windows (Using PowerShell)
# If you download/clone the repository and run the script from the repository root,
powershell -ExecutionPolicy bypass -File helper_tools\keygen.ps1# If you download the script separately and run the script from within the same directory,
powershell -ExecutionPolicy bypass -File keygen.ps1If you use this script, the server's common name will be clipshare_server, and the client's common name will be clipshare_client. You may change those names in the script you used.
clip_share accepts the following command line options.
Command line options
./clip_share [-h] [-s] [-r] [-R] [-d] [-D]
-h Help - Display usage and exit.
This takes priority over all other options.
-s Stop - Stop all instances of the server if any.
This takes priority over -r and -R.
-r Restart - Stop other instances of the server if any,
and restart the server. This option takes
precedence over the restart value in the
configuration file.
-R No-Restart - Start the server without restarting. This
option takes precedence over the restart
value in the configuration file.
-d Daemonize - Exit the main process after creating child
processes. This option is effective only on
Linux and macOS. (default)
-D No-Daemonize - Do not exit the main process after creating
child processes. This option is effective
only on Linux and macOS.
The ClipShare server can be configured using a configuration file. The configuration file should be named clipshare.conf.
The server searches for the configuration file in the following paths in the same order until it finds one.
- Current working directory where the server was started.
$XDG_CONFIG_HOMEdirectory if the directory exists (on Linux and macOS only).- Current user's home directory (also called user profile directory on Windows).
If it can't find a configuration file in any of the above directories, it will use the default values specified in the table below.
To customize the server, create a file named clipshare.conf in any of the directories mentioned above and add the following lines to that configuration file. You may ommit some lines to keep the default values.
Sample configuration file
app_port=4337
app_port_secure=4338
udp_port=4337
web_port=4339
insecure_mode_enabled=true
secure_mode_enabled=true
web_mode_enabled=false
server_cert=cert_keys/server.pfx
ca_cert=cert_keys/ca.crt
allowed_clients=allowed_clients.txt
working_dir=./path/to/work_dir
bind_address=0.0.0.0
restart=true
max_text_length=4194304
max_file_size=68719476736
display=1
client_selects_display=false
cut_sent_files=false
min_proto_version=1
max_proto_version=3
# Windows and macOS only
tray_icon=trueNote that all the lines in the configuration file are optional. You may omit some lines if they need to get their default values.
Configuration options
| Property | Description | Accepted values | Default |
|---|---|---|---|
insecure_mode_enabled |
Whether or not the application listens for unencrypted connections. The values true or 1 will enable it, while false or 0 will disable it. |
true, false, 1, 0 (Case insensitive) |
true |
secure_mode_enabled |
Whether or not the application listens for TLS-encrypted connections. The values true or 1 will enable it, while false or 0 will disable it. |
true, false, 1, 0 (Case insensitive) |
false |
web_mode_enabled |
Whether or not the application listens for TLS-encrypted connections from web clients if the web mode is available. The values true or 1 will enable it, while false or 0 will disable it. |
true, false, 1, 0 (Case insensitive) |
false |
app_port |
The port on which the application listens for unencrypted TCP connections. (Values below 1024 may require superuser/admin privileges) | Any valid, unused TCP port number (1 - 65535) | 4337 |
udp_port |
The port on which the application listens for UDP broadcasts of network scanning. (Values below 1024 may require superuser/admin privileges) | Any valid, unused UDP port number (1 - 65535) | 4337 |
app_port_secure |
The TCP port on which the application listens for TLS-encrypted connections. (Values below 1024 may require superuser/admin privileges) | Any valid, unused TCP port number (1 - 65535) | 4338 |
web_port |
The TCP port on which the application listens for TLS-encrypted connections for web clients. This setting is used only if web mode is available. (Values below 1024 may require superuser/admin privileges) | Any valid, unused TCP port number (1 - 65535) | 4339 |
server_cert |
The TLS key and certificate store file of the server. If this is not specified, secure mode (and web mode if available) will be disabled. | Absolute or relative path to the server's TLS certificate store PKCS#12 file | <Unspecified> |
ca_cert |
The TLS certificate file of the CA that signed the TLS certificate of the server. If this is not specified, secure mode (and web mode if available) will be disabled. | Absolute or relative path to the TLS certificate PEM file of the CA | <Unspecified> |
allowed_clients |
The text file containing a list of allowed clients (Common Name of client certificate), one name per line. If this is not specified, secure mode (and web mode if available) will be disabled. | Absolute or relative path to the allowed-clients file | <Unspecified> |
bind_address |
The address of the interface to which the application should bind when listening for connections. It will listen on all interfaces if this is set to 0.0.0.0 |
IPv4 address of an interface in dot-decimal notation (ex: 192.168.37.5) or 0.0.0.0 |
0.0.0.0 |
restart |
Whether the application should start or restart by default. The values true or 1 will make the server restart by default, while false or 0 will make it just start without stopping any running instances of the server. |
true, false, 1, 0 (Case insensitive) |
true |
working_dir |
The working directory where the application should run. All the files, that are sent from a client, will be saved in this directory. It will follow symlinks if this is a path to a symlink. The user running this application should have write access to the directory | Absolute or relative path to an existing directory | . (i.e. Current directory) |
max_text_length |
The maximum length of text that can be transferred. This is the number of bytes of the text encoded in UTF-8. | Any integer between 1 and 4294967295 (nearly 4 GiB) inclusive. Suffixes K, M, and G (case insensitive) denote x103, x106, and x109, respectively. | 4194304 (i.e. 4 MiB) |
max_file_size |
The maximum size of a single file in bytes that can be transferred. | Any integer between 1 and 9223372036854775807 (nearly 8 EiB) inclusive. Suffixes K, M, G, and T (case insensitive) denote x103, x106, x109, and x1012, respectively. | 68719476736 (i.e. 64 GiB) |
display |
The display that should be used for screenshots. | Display number (1 - 65535) | 1 |
cut_sent_files |
Whether to automatically cut the files into the clipboard on the Send Files method. | true, false, 1, 0 (Case insensitive) |
false |
client_selects_display |
Whether the client can override the default/configured display for screenshots in protocol version 3. The values true or 1 will allow overriding the default, while false or 0 will force using the default/configured display. |
true, false, 1, 0 (Case insensitive) |
false |
min_proto_version |
The minimum protocol version the server should accept from a client after negotiation. | Any protocol version number greater than or equal to the minimum protocol version the server has implemented. (ex: 2) |
The minimum protocol version the server has implemented |
max_proto_version |
The maximum protocol version the server should accept from a client after negotiation. | Any protocol version number less than or equal to the maximum protocol version the server has implemented. (ex: 3) |
The maximum protocol version the server has implemented |
method_get_text_enabledmethod_send_text_enabledmethod_get_files_enabledmethod_send_files_enabledmethod_get_image_enabledmethod_get_copied_image_enabledmethod_get_screenshot_enabledmethod_info_enabled |
These configuration keys map to methods in ClipShare. They separately define whether the corresponding method is enabled or not. The values true or 1 will allow clients to use the method, while false or 0 will disable the method. |
true, false, 1, 0 (Case insensitive) |
true |
tray_icon |
Whether the application should display a system tray icon (menu icon on macOS). This option is available only on Windows and macOS. The values true or 1 will display the icon, while false or 0 will prevent displaying the icon. |
true, false, 1, 0 (Case insensitive) |
true |
You may change these values. But it is recommended to keep the port numbers unchanged. If the port numbers are changed, client application configurations may also need to be changed as appropriate to connect to the server.
If you changed the configuration file, you must restart the server to apply the changes.
Note: If you prefer using the pre-built binaries from Releases, you can ignore this section and follow the instructions in the How to Use section.
Compiling ClipShare needs the following tools,
- gcc
- make
Linux
On Linux, these tools can be installed with the following command:
-
On Debian-based or Ubuntu-based distros,
sudo apt-get install gcc make
-
On Redhat-based or Fedora-based distros,
sudo yum install gcc make
-
On Arch-based distros,
sudo pacman -S gcc make
Windows
On Windows, these tools can be installed with MinGW.
In an MSYS2 environment, these tools can be installed using pacman with the following command:
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-makeYou may need to rename (or copy) the <MSYS2 directory>/mingw64/bin/mingw32-make.exe to <MSYS2 directory>/mingw64/bin/make.exe before running the command make
macOS
On macOS, these tools are installed with Xcode Command Line Tools.
Linux
The following development libraries are required.
-
libc
-
libx11
-
libxmu
-
libxcb-randr
-
libpng
-
libssl
-
libunistring
They can be installed with the following command:
-
On Debian-based or Ubuntu-based distros,
sudo apt-get install libc6-dev libx11-dev libxmu-dev libxcb-randr0-dev libpng-dev libssl-dev libunistring-dev
-
On Redhat-based or Fedora-based distros,
sudo yum install glibc-devel libX11-devel libXmu-devel libpng-devel openssl-devel libunistring-devel
-
On Arch-based distros,
sudo pacman -S libx11 libxmu libpng openssl libunistring
glibc should already be available on Arch distros. But you may need to upgrade it with the following command. (You need to do this only if the build fails)
sudo pacman -S glibc
(You may refer to docker/Dockerfile.* to see how to install the dependencies on various Linux distros)
Windows
The following development libraries are required.
- libz
- libpng16
- libssl (provided by OpenSSL)
- libunistring
In an MSYS2 environment, these tools can be installed using pacman with the following command:
pacman -S mingw-w64-x86_64-openssl mingw-w64-x86_64-libpng mingw-w64-x86_64-libunistringmacOS
The following development libraries are required.
These tools can be installed using Homebrew with the following command:
brew install openssl@3 libpng libunistring-
Open a terminal / command prompt / Powershell in the project directory
This can be done using the GUI or the
cdcommand. -
Run the following command to make the executable file
make
This will generate the executable named clip_share (or clip_share.exe on Windows).