ClipRelay

Copying a link on one machine and pasting it on another shouldn’t need email or a cloud account. ClipRelay syncs clipboard text and small files between your own devices through a relay, but the relay only ever sees encrypted blobs — devices share a room key derived from a room code, and without it the contents stay unreadable. Pick a room code, share it with your other machines, and your clipboard follows you.

What it does

• Syncs clipboard text between devices in the same room.
• Transfers files up to 50 MiB.
• Uses outbound WebSocket connections to a relay.
• Encrypts payloads client-side with XChaCha20-Poly1305.
• Keeps the relay stateless; it forwards opaque encrypted messages only.
• Provides a Windows tray client with status colours, send UI, options, and notifications.
• Provides a relay binary that can run on Linux or Windows.

Components

Component	Purpose
cliprelay-core	Shared framing, cryptography, room logic, and limits
cliprelay-relay	WebSocket relay server
cliprelay-client	Windows tray client

Security model

Room key derivation:

• room code is hashed with SHA256
• device IDs contribute to HKDF salt
• HKDF-SHA256 derives a 32-byte room key

Encryption:

• cipher: XChaCha20-Poly1305
• nonce includes sender identity material plus a monotonic counter
• receivers reject duplicate or stale counters

The relay does not know the room key and does not store message history. Offline clients miss messages.

Limits

Resource	Limit
Clipboard text	256 KiB
File transfer	50 MiB
Relay frame	300 KiB
Devices per room	10

Files larger than the frame limit are chunked.

Windows client workflow

1. Start ClipRelay.
2. Enter the relay URL, room code, and client name.
3. Wait for the tray status to become green.
4. Open the send window from the tray icon or global hotkey.
5. Send text or choose a file.
6. On the receiving device, apply clipboard text or save the file.

Tray status:

Colour	Meaning
Red	Disconnected or cannot reach relay
Amber	Connected but room key is not ready, often only one device in the room
Green	Connected and ready to send/receive

Client options

• Auto apply incoming clipboard text.
• Start with Windows using --background.
• Configure global hotkey, default Ctrl+Alt+C.
• Save client config at %LOCALAPPDATA%\ClipRelay\config.json.
• Save received files to Downloads\ClipRelay.

Run the relay in development

cargo run -p cliprelay-relay -- --bind-address 0.0.0.0:8080

Endpoints:

• /ws for WebSocket clients
• /healthz for health checks

Run the client in development

cargo run -p cliprelay-client -- --server-url wss://relay.example.com/ws --room-code my-secret-room --client-name Laptop

If launched without --room-code, the client shows a room choice dialog.

Install the relay on Linux

Download or build the relay binary, then use the included installer:

sudo ./deploy/install-relay-systemd.sh \
  --binary ./cliprelay-relay \
  --bind-address 127.0.0.1:8080

The installer creates a dedicated cliprelay user, writes /etc/cliprelay/relay.env, installs the binary under /opt/cliprelay/bin, installs a hardened systemd unit, enables it, and starts the service.

Verify:

sudo systemctl status cliprelay-relay
curl http://127.0.0.1:8080/healthz

Typical Caddy TLS proxy:

relay.example.com {
    handle /healthz {
        respond "ok" 200
    }
    handle /ws* {
        reverse_proxy 127.0.0.1:8080
    }
}

Clients then connect to wss://relay.example.com/ws.

Build and test

git clone https://github.com/Swatto86/ClipRelay.git
cd cliprelay
cargo check
cargo test -p cliprelay-core
cargo test -p cliprelay-relay --test e2e_relay
cargo test -p cliprelay-client

Build the relay:

cargo build --release -p cliprelay-relay

Troubleshooting

Tray stays red

Check relay URL, TLS certificate, firewall, and whether /ws is proxied correctly.

Tray stays amber

Usually only one device is present or room key negotiation has not completed. Start a second client with the same room code.

File transfer fails

Confirm file size is below 50 MiB and both clients remain online during the transfer.

Clipboard did not update

If Auto apply is off, accept the popup manually. Also check OS clipboard permissions and whether another clipboard manager overwrote the value.

Links

• GitHub: https://github.com/Swatto86/ClipRelay
• Releases: https://github.com/Swatto86/ClipRelay/releases