Clipman Server Manual

Clipman Server is optional infrastructure for Clipman. It hosts encrypted or compressed .clipdb history databases so multiple Clipman clients can synchronize through one server instead of relying only on a cloud-synced folder or network share.

The server does not know the Clipman history password and does not decrypt clipboard history. Clipman clients unlock, merge, and save history locally, then upload the resulting database blob with a revision check.

Downloads and Client App
Server Program
Security Model
Recommended Linux Install
Docker and GHCR
First Run
Run at System Start
Updates
Temporary Browser Setup
Connection Details File
Commented Settings Example
Linux Helper Commands
Starting With Existing History
Client Settings
Private LAN or VPN
Private-CA HTTPS
VPS or Public Internet
Files and Paths
Multiple Databases
Database Maintenance
Backups
Logs
API Summary

Downloads and Client App

The normal Clipman app download is the client. It does not include the server. Download Clipman Server separately when you want to host shared history yourself.

Clipman releases are published at https://github.com/OnjLouis/Clipman/releases. The main project page is https://github.com/OnjLouis/Clipman.

Server Program

The Clipman Server package runs:

clipman_server.py

It runs on Linux, macOS, and Windows with Python 3. The Windows EXE and macOS app are background wrappers around this same Python server, not separate native server implementations. The same server program is used across platforms so the safety model stays consistent: random first-run port, random bearer token, password-scoped database buckets, cheap revision polling, rolling backups, private file permissions where supported, rotating logs, database-ID log redaction, and optional direct TLS.

Security Model

The server stores raw .clipdb blobs. If you use a Clipman history password, clipboard text remains encrypted on the server. The server still has sensitive responsibilities:

It holds the server bearer token.
It accepts uploads from clients that know that token.
It sees connection timing, database blob sizes, and client IP addresses.
If exposed insecurely, an attacker could try to replace or delete encrypted blobs even if they cannot read them.

Use one of these deployment patterns:

Scenario	Recommended transport
Testing on one machine	Localhost only.
Home LAN, Tailscale, or private VPN	`clipman://host:port` in Clipman clients.
VPS or public internet	HTTPS, either direct TLS or a trusted reverse proxy.

Do not expose plain HTTP or plain clipman:// directly to the public internet.

Recommended Linux Install

On Linux, especially a Raspberry Pi or small always-on server, run the installer from the extracted server package:

sh Linux/install-clipman-server.sh

The installer copies the server into a user-local application folder, creates a launcher, writes first-run settings, and creates importable and plain text connection files:

Program:            ~/.local/lib/clipman-server/clipman_server.py
Launcher:           ~/.local/bin/clipman-server
Settings:           ~/.config/clipman-server/clipman-server-settings.json
Importable connection: ~/.config/clipman-server/clipman-server-connection.clpconf
Readable connection:   ~/.config/clipman-server/clipman-server-connection.txt

The installer supports systemd and runit. With user systemd, it writes a service and update timer under ~/.config/systemd/user and enables user lingering so they continue running after the last login ends and start during boot without an interactive login. If system policy prevents the installer from enabling lingering, it prints the exact administrator command required. On a runit system such as Void Linux, a persistent per-user service requires turnstile; when turnstile is installed, the installer writes native runit service directories under ~/.config/service. The installer detects the service manager automatically, or it can be selected explicitly with CLIPMAN_SERVER_INIT_SYSTEM=systemd or CLIPMAN_SERVER_INIT_SYSTEM=runit. This keeps the extracted download folder disposable and leaves the home directory tidy.

If runit is available without turnstile, the program and command-line helpers are still installed, but no persistent per-user service is created. On Void Linux, install turnstile with sudo xbps-install -S turnstile, enable its system service, and run the Clipman Server installer again.

Existing System Services

Administrators who already run Clipman Server as a hardened system service can add the same management and update commands without replacing that service or moving its settings and data. From the extracted package, set the existing paths and service name explicitly:

sudo env \
  CLIPMAN_SERVER_APP_DIR=/path/to/server/program \
  CLIPMAN_SERVER_CONFIG_FILE=/path/to/server-settings.json \
  CLIPMAN_SERVER_SERVICE=your-service.service \
  sh Linux/install-clipman-server-system-helper.sh

For an existing native runit service, set CLIPMAN_SERVER_INIT_SYSTEM=runit, use its directory name without a .service suffix, and pass its service directory if it is not under /etc/sv:

sudo env \
  CLIPMAN_SERVER_INIT_SYSTEM=runit \
  CLIPMAN_SERVER_APP_DIR=/path/to/server/program \
  CLIPMAN_SERVER_CONFIG_FILE=/path/to/server-settings.json \
  CLIPMAN_SERVER_SERVICE=your-service \
  CLIPMAN_SERVER_SERVICE_FILE=/etc/sv/your-service \
  sh Linux/install-clipman-server-system-helper.sh

The installer validates every required existing file, adds a system clipmanserver helper and an optional disabled update service, and leaves the running service untouched. System-wide runit services use native service directories under /etc/sv and are enabled through /var/service; they do not require turnstile. Future updates replace only packaged program and documentation files. The existing service definition, token-bearing settings, database buckets, certificates, logs, backups, ownership, and listening configuration remain in their current locations.

Docker and GHCR

Clipman Server can also run as a container. This is useful for NAS, VPS, homelab, or reverse-proxy setups where services are managed as containers instead of directly installed programs.

The published image is:

ghcr.io/onjlouis/clipman-server:latest

A typical reverse-proxy deployment looks like this:

docker run --detach \
  --name clipman-server \
  --restart unless-stopped \
  --network dockernet \
  -e CLIPMAN_IS_BEHIND_REVERSE_PROXY=true \
  -e CLIPMAN_PORT=8080 \
  -v /data/docker/clipman:/data \
  ghcr.io/onjlouis/clipman-server:latest

The container stores settings, connection details, databases, backups, and logs under the mounted /data volume. Keep that volume backed up. The container listens on 0.0.0.0:8080 by default inside the container so a reverse proxy or Docker network can reach it.

If you are using Caddy, nginx, Traefik, or another TLS reverse proxy, leave Clipman Server as plain HTTP inside the private Docker network and expose only the reverse proxy to the public internet. Set CLIPMAN_IS_BEHIND_REVERSE_PROXY=true so the server permits that private container listener. Clipman clients should use the public HTTPS address from the reverse proxy.

For a server whose published port is reachable only through a trusted LAN or VPN, explicitly allow that private plain-HTTP transport:

docker run --detach \
  --name clipman-server \
  --restart unless-stopped \
  -p 8080:8080 \
  -e CLIPMAN_ALLOW_INSECURE_REMOTE=true \
  -v /opt/clipman-server:/data \
  ghcr.io/onjlouis/clipman-server:latest

Do not use CLIPMAN_ALLOW_INSECURE_REMOTE=true for a port exposed directly to the public internet. Without TLS, reverse-proxy mode, or this deliberate trusted-network override, the container explains the required choices and stops instead of opening an insecure listener.

Useful container environment variables:

Variable	Meaning
`CLIPMAN_DATA_DIR`	Container data folder. Defaults to `/data`.
`CLIPMAN_HOST`	Listen host inside the container. Defaults to `0.0.0.0`.
`CLIPMAN_PORT`	Listen port inside the container. Defaults to `8080`.
`CLIPMAN_ADVERTISE_HOST`	Host written into generated connection files. Set this when `CLIPMAN_HOST` is a wildcard such as `0.0.0.0`; otherwise the server runs but does not generate an unusable connection file.
`CLIPMAN_IS_BEHIND_REVERSE_PROXY`	Set to `true` when TLS is handled by a reverse proxy.
`CLIPMAN_ALLOW_INSECURE_REMOTE`	Set to `true` only when the published port is restricted to a trusted LAN or VPN.
`CLIPMAN_CERT_FILE` and `CLIPMAN_KEY_FILE`	Optional direct TLS certificate and key paths inside the container.

The server ZIP also includes a Docker folder with a Dockerfile for users who prefer to build the image locally from the downloaded package.

First Run

Windows and macOS users should normally start Clipman Server through the app wrapper, not a terminal window. The wrapper starts the shared Python server in the background, keeps it out of Alt-Tab, the Dock, and Command-Tab, redirects output to logs, and provides a tray or status-menu interface for common actions.

Windows

Run:

Windows\Clipman Server.exe

Clipman Server appears in the Windows notification area. It does not open a console window and does not appear as a normal Alt-Tab window. Right-click the Clipman Server notification-area icon to copy connection details, open settings, open logs, restart the server, enable or disable startup, or quit.

The Windows EXE contains the shared server script and extracts it into %LOCALAPPDATA%\Clipman Server\Runtime when it starts. Windows users do not need to keep the Linux or macOS folders after extracting the package. Keep Manual.html and LICENSE.txt somewhere accessible for reference. Python 3 must still be installed because the EXE is a background wrapper around the shared Python server, not a bundled Python runtime.

macOS

Run:

macOS/Clipman Server.app

Clipman Server appears in the macOS menu bar. It does not keep a Terminal window open and does not appear in the Dock or Command-Tab. Click the Clipman Server menu-bar item to copy connection details, open settings, open logs, restart the server, enable or disable login startup, or quit.

The macOS app bundles the shared server script in its Resources folder and runs it with Python 3. Python 3 must be installed. The wrapper looks for /opt/homebrew/bin/python3, /usr/local/bin/python3, and /usr/bin/python3. On a clean Mac, install Python 3 with Homebrew, or install Apple's Command Line Tools if that provides /usr/bin/python3 on your system.

Linux

For Linux, especially Raspberry Pi or VPS use, prefer the installer described above. For a temporary manual run from the extracted package, use:

python3 clipman_server.py

Command-Line Diagnostics

For troubleshooting only, users who kept the full server package can run the shared Python server directly from the package root:

python3 clipman_server.py        # macOS or Linux
py -3 clipman_server.py          # Windows with the Python launcher

This is useful when you deliberately want console output. It is not the recommended everyday way to run the server. On Windows and macOS, the wrapper menu's Open settings folder, Open logs folder, and Copy connection details commands are usually easier than running the server by hand.

On first run, the server creates a settings file with a random persistent listening port, a random bearer token, a private data directory, a managed log file, and importable and readable connection files beside the settings file. New ports are chosen outside the range Windows normally reserves for temporary connections, so a Windows restart is less likely to make the saved port unavailable.

Later starts read existing settings without replacing the settings file when nothing has changed. Settings introduced by a newer server are applied in memory when they are absent from an older file; the file is not expanded merely because those defaults were missing. First-run defaults and deliberate command-line changes are still saved. Clipman Server also prevents two server processes from using the same data folder at once. A second process exits with a clear message; after a normal stop or a crash, the operating-system lock is released automatically, so an old lock marker does not require manual cleanup.

Show the token later with:

python3 clipman_server.py --show-token

Run at System Start

Clipman Server is intended to run quietly in the background. Use the platform startup method below instead of leaving a terminal open.

Windows Startup

Start Windows\Clipman Server.exe.
Open the Clipman Server notification-area menu.
Choose Run at Windows startup.

The Windows wrapper writes a per-user startup entry and starts the Python server hidden. If you later move the server folder, turn startup off and back on so the startup entry points to the new location.

macOS Login Startup

Start macOS/Clipman Server.app.
Open the Clipman Server status menu.
Choose Run at Login.

The macOS wrapper creates a per-user LaunchAgent that starts the menu-bar server app at login. If you later move the app, turn Run at Login off and back on so the LaunchAgent points to the new location.

Linux Startup

The Linux installer writes a user service for systemd or, with turnstile, runit. The portable helper starts the selected service type:

clipmanserver start

On systemd, clipmanserver start also checks user lingering and attempts to enable it. The equivalent direct setup is:

sudo loginctl enable-linger "$USER"
systemctl --user enable --now clipman-server.service

clipmanserver status reports whether start-at-boot without login is enabled. The installer does not later disable lingering automatically because other per-user services may depend on it. To disable it deliberately after removing all such services, run sudo loginctl disable-linger "$USER".

On runit, the service is supervised from ~/.config/service/clipman-server. Use clipmanserver status, clipmanserver restart, and clipmanserver stop for everyday service control with either service manager.

Updates

Clipman Server updates are published as a separate ClipmanServer-... ZIP on the Clipman releases page. The server package can update itself without changing Clipman client settings or server databases, because those live in per-user data folders rather than inside the extracted download folder.

Server 2.6.4 improves private HTTPS certificate creation. Interactive Linux setup detects active non-loopback IPv4 and IPv6 addresses, lists them and asks whether to include them; Windows presents an accessible checked address list; and Mac offers Include All, Skip or Cancel. Each platform also accepts additional comma-separated hostnames. Existing explicit --cert-host and --cert-ip commands remain non-interactive for scripts and containers.

Server 2.6.3 makes user-systemd installations genuinely persistent on headless systems such as Raspberry Pi OS Lite. The installer and clipmanserver start detect and enable user lingering when permitted, clipmanserver status reports whether boot-without-login is enabled, and a blocked setup receives the exact administrator command required. This resolves issue #60 without adding unnecessary keep-alive traffic.

Server 2.6.2 fixes updates on runit systems such as Void Linux. Update backups preserve persistent service definitions without trying to copy the live supervise directory or its named pipes, and rollback retains active supervision state instead of deleting it. Users affected while running an older updater can install the current server package once with the normal Linux installer; later clipmanserver update commands use the corrected updater. This closes issue #54.

Server 2.6.1 preserves the configured service account as the owner when an administrator changes settings or creates a temporary setup link on a hardened system installation. This keeps the live service able to read its private 0600 settings and setup-state files.

Server 2.6.0 adds temporary browser onboarding. A server administrator can create a short-lived setup page, open it on a new device, and download the existing importable .clpconf connection file without manually copying an address or token. The random setup code is stored only as a SHA-256 hash, setup paths are redacted from logs, the page sends no analytics or external resources, and the link expires by both time and download count. Public setup pages require HTTPS; plain HTTP is accepted only for local, private-network, or VPN addresses. The feature was inspired by Michael Babcock's article How I Got an AI Assistant to Set Up My Own Private Clipboard Sync Server.

Server 2.5.0 adds native runit and turnstile support for Void Linux and other runit systems while retaining the existing systemd and manual-start choices. It also prevents two server processes from writing to the same data folder, and ordinary startup no longer rewrites an existing settings file merely to apply missing defaults in memory. Installed Linux maintenance commands briefly stop an active managed service, perform the protected operation, and restart it even when the operation is refused. This incorporates pull request #51 and closes the maintainer review in issue #52.

Server 2.4.3 adds supported management and transactional updates for existing system-wide Linux services. Administrators can retain a dedicated service account and hardened service definition while using the normal clipmanserver commands. Program replacement preserves file ownership and permissions, verifies the restarted server locally, and restores the previous program if the health check fails.

Server 2.4.2 adds a safe Linux command for changing the listening host, prevents connection files from containing unusable wildcard addresses, and restores the previous working configuration if a new address cannot start. This resolves issue #48.

Server 2.4.1 fixes Linux updates for HTTPS installations whose advertised address cannot connect back to the server's private listening port. The updater now checks the local listener while still validating the advertised TLS certificate name. If a service genuinely fails to start, the update error includes useful service-status details before restoring the previous program. This resolves issue #47.

Windows and macOS check daily for server updates and install them automatically by default. Use Install updates automatically in the notification-area or menu-bar menu to turn that behavior off or back on. Check for updates remains available for an immediate manual check. If a newer server ZIP is available, the wrapper downloads the ZIP, closes the wrapper, replaces the platform-specific server app, and starts the updated wrapper again.

Server 2.3.0 aligns the packaged server version with Clipman 2.3.0, makes automatic updates the default on Windows, macOS and new Linux installations, and ensures server updaters ignore ordinary Clipman client releases. Server and client releases remain independent after this point.

The Windows and macOS wrappers also support these command-line switches for scripts and diagnostics:

Switch	Purpose
`--version`	Show the server wrapper version.
`--check-updates`	Check GitHub releases for a newer Clipman Server package.
`--install-update`	Check for a newer Clipman Server package and install it if one is available.
`--install-update --silent`	Install a newer server package without prompting when possible.

Installed Linux servers provide:

clipmanserver check-update
clipmanserver update

Every server updater downloads the exact versioned server ZIP over HTTPS and requires its GitHub SHA-256 digest before replacing program files. Linux additionally rejects unsafe archive paths, checks the package manifest, and stages the replacement. A normal per-user update backs up its installed program, launcher, helper, and service files. A system-managed update snapshots only the program files it is permitted to replace. Neither mode includes settings, databases, logs, backups, certificates, or tokens. After installation it restarts the server and checks the health endpoint. If the updated service does not become healthy, the previous program files are restored and restarted automatically.

New Linux installations support automatic daily updates with a systemd user timer or a supervised runit update service. Use these commands to inspect, enable or disable them:

clipmanserver enable-auto-updates
clipmanserver update-status
clipmanserver disable-auto-updates

The systemd timer waits at least 15 minutes after boot, runs at most once per day with a randomized delay, and remembers a missed run. The runit update service waits 15 minutes after it starts and then checks once per day while it remains supervised. Container installations should continue updating by pulling a newer container image rather than modifying a running container.

Unavailable Listening Port

If another program or the operating system reserves the saved listening port, Clipman Server reports port unavailable and stops instead of repeatedly restarting. Settings, tokens, certificates, databases, and backups remain unchanged. This resolves issue #37.

On Windows or macOS, open the server's notification-area or menu-bar menu and choose Change Listening Port. The server suggests an available persistent port, saves it, refreshes both connection files, and restarts. On an installed Linux server, run:

clipmanserver port

You can also specify a checked port directly, for example clipmanserver port 25766. After changing the port, update the server address on every Clipman client or import the refreshed clipman-server-connection.clpconf file. Changing the port does not change the token or choose a different database bucket.

Temporary Browser Setup

Temporary browser setup is an easier way to configure another Clipman client without leaving a permanent connection page online. On Windows or macOS, open the server menu and choose Create Temporary Setup Link. The server copies the URL, opens it in the default browser, and reports its expiry and download limit. Choose Revoke Temporary Setup Link as soon as onboarding is complete.

On an installed Linux server, use:

clipmanserver setup-link
clipmanserver revoke-setup-link

The default link lasts 30 minutes and permits five connection-file downloads. Optional values set the lifetime in minutes and download count:

clipmanserver setup-link 10 2

Creating another link replaces the previous one. The server stores only a hash of the random setup code in clipman-server-setup-link.json; it does not store the usable setup URL. A successful connection-file download consumes one use before the file is sent, so an interrupted transfer can consume a use without exposing additional credentials. Browser previews and HEAD requests do not consume a use.

The page contains one explicit connection-file download, concise platform instructions, links to current Clipman downloads, and no scripts, analytics, external images, or automatic download. Browser identification is used only to put the most relevant instruction first; instructions and download links for every platform remain available.

The downloaded file contains the permanent server token and, when configured, the public private-certificate authority. It never contains the Clipman history password. Treat it like the ordinary connection file: transfer it only to a device you control and delete it after import.

For a private LAN, Tailscale, or another VPN, Clipman Server can infer the browser URL from AdvertiseHost and Port. For a public reverse proxy, add its HTTPS root to the live settings file, for example:

"SetupBaseUrl": "https://clipman.example"

Public HTTP setup links are refused even if the main server listener was deliberately allowed to use insecure remote HTTP. Direct private-CA HTTPS can also be used, but the browser must already trust that private authority; the downloaded .clpconf continues to provide app-specific trust to Clipman itself.

Connection Files

clipman-server-connection.clpconf exists so users do not have to open or edit JSON settings or copy individual values. Import it from the server section of Clipman Settings or Preferences. On Android and iOS, you can instead open the file directly from the system file browser. Clipman requires the normal device unlock, displays the server address for review, keeps the token hidden, requires a nonblank history password, and waits for Save before applying it.

The server also writes clipman-server-connection.txt for readable manual setup and older clients. It contains:

Server address:
Port:
Token:

Both files contain the private server token. After every Clipman client has been configured, delete them or move the details to a password manager. If both are deleted, the server will not recreate them on every launch. On Windows and macOS, use the wrapper menu's Copy connection details command when you need the address, port, and token again.

Default connection-details locations are:

Platform	Importable connection file
Windows wrapper	`%LOCALAPPDATA%\Clipman Server\clipman-server-connection.clpconf`
macOS wrapper	`~/Library/Application Support/Clipman Server/clipman-server-connection.clpconf`
Linux installer	`~/.config/clipman-server/clipman-server-connection.clpconf`
Direct package run	`./Settings/clipman-server-connection.clpconf`

On Linux installs, recreate the file intentionally with:

clipmanserver connection

Without the Linux installer, run the Python server directly:

python3 clipman_server.py --write-connection-info        # macOS or Linux
py -3 clipman_server.py --write-connection-info          # Windows with the Python launcher

Commented Settings Example

The server package includes a commented settings example:

clipman-server-settings.example.jsonc

This file lists every server setting, explains what it does, and shows common values for private networks, VPNs, direct HTTPS, logging, and backups. It is meant to be read beside the manual when the real settings file feels too terse.

The live settings file is ordinary JSON and does not support comments. Do not paste the whole commented example over the live settings file. Instead, copy the specific setting names and values you want into clipman-server-settings.json, then restart Clipman Server.

If you run Clipman Server through the Windows or macOS wrapper, use the wrapper menu to open the settings folder. On Linux installs, the settings file normally lives at:

~/.config/clipman-server/clipman-server-settings.json

Linux Helper Commands

The Linux installer creates two launchers in ~/.local/bin:

Command	Purpose
`clipman-server`	Runs the server program directly and accepts every advanced command-line switch.
`clipmanserver`	Linux-only friendly helper for common admin tasks.

Helper commands:

clipmanserver start
clipmanserver stop
clipmanserver restart
clipmanserver status
clipmanserver list
clipmanserver list-json
clipmanserver prune [days]
clipmanserver delete <database-id>
clipmanserver force-delete <database-id>
clipmanserver console
clipmanserver token
clipmanserver connection
clipmanserver host [listening-address] [client-address]
clipmanserver version
clipmanserver check-update
clipmanserver update
clipmanserver enable-auto-updates
clipmanserver disable-auto-updates
clipmanserver update-status

start, stop, restart, and status use the installed user systemd or turnstile-managed runit service when available. console runs the server in the current terminal so you can see messages directly. Pressing Ctrl+C in console mode stops the server cleanly. host without an address reports the current listener; with an address it updates the setting, refreshes the connection files, restarts, and verifies the server. If it fails, the previous configuration is restored. list shows shortened IDs for easy reading; list-json shows full IDs for maintenance. prune moves buckets inactive for the configured number of days, or for the number you type after the command. delete refuses buckets touched in the last 24 hours; force-delete is the deliberate override for a bucket you have checked carefully. Because the server protects its data root with an exclusive process lock, the installed helper briefly stops a running managed service for confirmed prune or delete work and always attempts to restart it afterward. The update commands use the safe update and rollback process described above.

Starting With Existing History

Do not manually copy an existing .clipdb into the server's database folders. Server database buckets are derived by Clipman clients from the server token and the Clipman history password. The server deliberately does not know that history password, so it cannot safely decide which bucket an imported file belongs in.

To start a new server from an existing history, use the Clipman client that already has the history you want:

Install and start Clipman Server.
Import clipman-server-connection.clpconf in Clipman Preferences, or copy the address and token from the readable text file.
On the Clipman client that already has the desired history, open Preferences.
Set Storage type to Clipman Server, enter the server address and token, and keep the same Clipman history password.
Let that client connect first. It will upload or merge the existing history into the correct password-scoped server bucket.
Then connect the other clients using the same server token and history password.

Client Settings

In Clipman Preferences:

Choose Import server file and select clipman-server-connection.clpconf, or enter the server host and token manually.
Review the imported server address, then save Preferences.
Keep the Clipman data folder local to that machine. It is used for settings and cache.

The server path is an additional storage path, not a replacement for local cache and settings.

Private LAN or VPN

For an installed Tailscale-only server, bind directly to its Tailscale address:

clipmanserver host 100.64.0.10

Replace the example with the server's own Tailscale address. If a server has already been deliberately configured to allow an all-interface HTTP listener, give clients a real reachable address by providing both values:

clipmanserver host 0.0.0.0 100.64.0.10

The first value controls where the server listens. The optional second value is written to connection files for clients. Wildcard values such as 0.0.0.0 and :: are never exported as client destinations. The host command does not weaken HTTP security checks or enable public insecure listening.

Then configure Clipman clients with:

clipman://server-name-or-tailscale-ip:port

Only use this when the port is reachable only from trusted private networks or VPN clients.

Private-CA HTTPS

Clipman Server can create its own private certificate authority and a server certificate for people who want HTTPS without buying a certificate or publishing a private server through public DNS. OpenSSL is required. The generated private keys stay in the server settings folder and must never be copied to client devices.

On Windows, choose Create or renew HTTPS certificate from the Clipman Server notification-area menu. On macOS, use the same command in the menu-bar menu. On an installed Linux server, run:

clipmanserver cert

Interactive certificate creation detects the computer's active non-loopback IP addresses, shows the complete list, and asks whether to include them. It then accepts optional additional hostnames as a comma-separated list. Localhost, the configured listening and advertised addresses, and the computer name remain included automatically. Review detected addresses before accepting them, especially on computers with temporary VPN or IPv6 addresses.

For scripts and unattended setup, repeat --cert-host and --cert-ip explicitly for every DNS name or address clients use, for example clipmanserver cert --cert-host server-name --cert-ip 100.64.0.10. Supplying either option keeps the command non-interactive. The server reuses its existing private authority during normal renewal, creates a new server certificate valid for 397 days, updates its HTTPS settings, and rewrites the connection files with an https:// address. Creating a new authority with --new-ca is an explicit recovery operation because every connected client must import the replacement authority.

Connect Current Clients

Transfer clipman-server-connection.clpconf from the server settings folder through a channel you trust. The file contains the private server token as well as the public authority.
Open or import the file in Clipman. Review the displayed HTTPS host, authority subject, expiry date, and SHA-256 fingerprint.
Enter the history password separately, then choose Save or Apply. Importing alone does not change the active connection.
Confirm that synchronization succeeds before removing any older operating-system trust entry.

Current clients validate the embedded authority and use it only inside Clipman, only for the reviewed HTTPS host. Hostname, validity, signing usage, and server-certificate purpose checks still apply. When an embedded authority is configured, Clipman does not fall back to a public system authority for that profile. Exporting the connection again preserves the authority when it still matches the saved host.

Windows and macOS server menus can copy the authority fingerprint. On an installed Linux server, run:

clipmanserver fingerprint

Older Clients and Recovery

Older clients do not understand the embedded authority. For those clients, or for manual recovery, use Share certificate authority in the Windows or macOS server menu, or run:

clipmanserver share-ca

This temporarily serves the public clipman-server-ca.crt at a random high port and unguessable path. It stops after the first successful download or ten minutes. Use it only over a trusted LAN or VPN, and compare the SHA-256 fingerprint through a separate trusted channel. The sharing command never serves either private key.

Legacy operating-system installation locations are Current User Trusted Root Certification Authorities on Windows, Keychain Access trust settings on macOS, user CA settings on Android, and configuration profiles plus Certificate Trust Settings on iPhone or iPad. After upgrading, import the refreshed .clpconf, verify synchronization, remove the old operating-system authority, restart Clipman, and verify synchronization again. Until the old authority is removed, it remains trusted outside Clipman.

A different address will fail hostname validation even when the authority is correct. Changing the saved host clears app-specific authority trust and requires review or re-import. Removing the authority does not remove the server address, token, or history password, but a private-CA server will stop synchronizing unless the authority is imported again or remains trusted by the operating system. Clipman Server writes a warning to its log when the active certificate has fewer than 30 days remaining, and its health response includes the certificate expiry date. If either the certificate or key is missing, unreadable, or mismatched, the server refuses to open a listener and reports the exact configuration problem instead of falling back to HTTP.

The embedded-authority flow applies directly when Clipman Server terminates TLS itself. A reverse proxy with a publicly trusted certificate needs no embedded authority. A reverse proxy using a private authority requires that authority to be imported separately and bound to the public HTTPS host.

Docker

Set CLIPMAN_SELF_SIGNED_CERT=true to create and reuse a private authority in the mounted /data volume. Optional comma-separated CLIPMAN_CERT_HOSTS and CLIPMAN_CERT_IPS values add names and addresses to the server certificate. Keep the volume persistent: deleting it also deletes the private authority needed for renewal.

VPS or Public Internet

For a VPS or any internet-facing deployment, use HTTPS.

Direct TLS example:

python3 clipman_server.py \
  --host 0.0.0.0 \
  --advertise-host example.com \
  --cert-file /etc/letsencrypt/live/example.com/fullchain.pem \
  --key-file /etc/letsencrypt/live/example.com/privkey.pem

--host controls where the server listens. --advertise-host controls what host name is written to the connection files. Use the certificate's DNS name as the advertised host when the server binds to a private IP address.

You can also run the server on localhost and put it behind a reverse proxy such as nginx, Caddy, or Apache. In that case, the public client address should still be HTTPS.

Files and Paths

When run directly from the extracted server package, the settings and connection files stay beside that package:

Settings file:      ./Settings/clipman-server-settings.json
Importable connection: ./Settings/clipman-server-connection.clpconf
Readable connection:   ./Settings/clipman-server-connection.txt

Default data and log locations depend on the operating system:

Linux

Settings:           ~/.config/clipman-server/clipman-server-settings.json
Importable connection: ~/.config/clipman-server/clipman-server-connection.clpconf
Readable connection:   ~/.config/clipman-server/clipman-server-connection.txt
Databases:          ~/.local/share/clipman-server/Databases/<database-id>/clipman-history.clipdb
Backups:            ~/.local/share/clipman-server/Databases/<database-id>/ServerBackups/
Logs:               ~/.local/state/clipman-server/logs/clipman-server.log

Windows

Settings:           %LOCALAPPDATA%\Clipman Server\clipman-server-settings.json
Importable connection: %LOCALAPPDATA%\Clipman Server\clipman-server-connection.clpconf
Readable connection:   %LOCALAPPDATA%\Clipman Server\clipman-server-connection.txt
Runtime script:     %LOCALAPPDATA%\Clipman Server\Runtime\clipman_server.py
Databases:          %LOCALAPPDATA%\Clipman Server\Databases\<database-id>\clipman-history.clipdb
Backups:            %LOCALAPPDATA%\Clipman Server\Databases\<database-id>\ServerBackups\
Logs:               %LOCALAPPDATA%\Clipman Server\logs\clipman-server.log

macOS

Settings:           ~/Library/Application Support/Clipman Server/clipman-server-settings.json
Importable connection: ~/Library/Application Support/Clipman Server/clipman-server-connection.clpconf
Readable connection:   ~/Library/Application Support/Clipman Server/clipman-server-connection.txt
Runtime script:     Clipman Server.app/Contents/Resources/clipman_server.py
Databases:          ~/Library/Application Support/Clipman Server/Databases/<database-id>/clipman-history.clipdb
Backups:            ~/Library/Application Support/Clipman Server/Databases/<database-id>/ServerBackups/
Logs:               ~/Library/Logs/Clipman Server/logs/clipman-server.log

For a system service, use admin-owned paths such as:

/etc/clipman-server/clipman-server-settings.json
/var/lib/clipman-server
/var/log/clipman-server/clipman-server.log

Multiple Databases

The server can serve multiple separate Clipman histories. Clients derive a server-side database ID from the server token and the Clipman history password.

Clients using the same token and same history password use the same database bucket. Clients using a wrong or different history password use a different bucket and cannot overwrite the existing history.

Database Maintenance

The server records small metadata beside each database bucket, including when the bucket was first seen, last seen, and last written. This helps you spot old wrong-password buckets or test databases without opening the clipboard database itself. Last-seen metadata is throttled so routine polling does not write to disk every few seconds.

List active database buckets:

clipmanserver list

To show full IDs for delete or scripts:

clipmanserver list-json

Or, without the Linux helper:

python3 clipman_server.py --list-databases
python3 clipman_server.py --list-databases-json

The server cannot reliably know that a database is permanently abandoned. A laptop might be turned off, a user might be travelling, or a client might only connect occasionally. For that reason, Clipman Server never silently erases database buckets. Stale cleanup moves old buckets into DeletedDatabases so you can restore or permanently remove them later.

Automatic stale cleanup is disabled by default. To enable it, set DatabasePruneDays in the server settings file. For example, DatabasePruneDays: 30 moves buckets that have not been seen or written for 30 days. The server checks once on startup and then every DatabasePruneIntervalHours, which defaults to 24 hours.

To review stale buckets without changing anything:

clipman-server --prune-databases-days 30              # Linux installed launcher
python3 clipman_server.py --prune-databases-days 30   # direct package run

To move stale buckets out of the active database folder on Linux using the configured number of days:

clipmanserver prune

To specify the number of days directly:

clipmanserver prune 30

Without the Linux helper, use the direct server command:

clipman-server --prune-databases-days 30 --confirm              # Linux installed launcher
python3 clipman_server.py --prune-databases-days 30 --confirm   # direct package run

To move one known bucket by ID on Linux:

clipmanserver delete <database-id>

This command refuses to move a bucket touched in the last 24 hours. That protects a real active database from being removed by mistake. If you have checked the full ID and are certain the recent bucket is disposable, use the deliberate override:

clipmanserver force-delete <database-id>

Without the Linux helper, use the direct server command:

clipman-server --delete-database <database-id> --confirm              # Linux installed launcher
python3 clipman_server.py --delete-database <database-id> --confirm   # direct package run

To bypass the 24-hour guard without the helper, add --force-recent.

These commands move database folders into DeletedDatabases. They do not shred or permanently erase them. Keep or delete that folder according to your own backup policy after you are certain the data is no longer needed.

Backups

Backups are raw .clipdb copies. The server does not decrypt them.

BackupIntervalMinutes: 60
BackupRetentionHours: 24
MaxBackups: 48
CreateBackupBeforeEveryUpload: true

Backups live under each database bucket:

Databases/<database-id>/ServerBackups/

When an upload is byte-for-byte identical to the database already on the server, the server returns the current revision without rewriting the file or creating another backup. This avoids unnecessary disk writes on small hosts such as Raspberry Pi systems.

MaxDatabaseBytes limits the size of one uploaded database. The default is 67108864 bytes, or 64 MiB. Requests above that limit are rejected without changing the stored database. Increase it only if a legitimate Clipman history grows beyond that size.

Logs

The server writes rotating logs. Database IDs are redacted from request logs as:

/api/v1/database/<database-id>

Routine successful polling requests are suppressed so a busy set of clients does not create excessive log noise.

The health endpoint includes lightweight in-memory runtime counters such as uptime, request count, unique clients, uploaded bytes, downloaded bytes, and conflict count. These counters reset when the server restarts. They are kept in RAM so the server does not constantly write statistics to disk on small hosts.

When the server shuts down cleanly, it writes a one-line runtime summary to the log. This is useful for checking how much traffic the server handled between runs without creating another data file.

API Summary

Unauthenticated:

GET /api/v1/health

Authenticated with Authorization: Bearer <server-token>:

HEAD /api/v1/database/<database-id>
GET  /api/v1/database/<database-id>
PUT  /api/v1/database/<database-id>

Downloads return X-Clipman-Revision and ETag. Uploads may include If-Match. If another client wrote first, the server returns HTTP 409 so the client can download, merge, and retry instead of overwriting newer history.

Clients normally poll with HEAD. If polling fails repeatedly, clients back off and retry later while continuing to use their local cache.