Repository navigation
Relay Operations
The relay is an Axum HTTP/WebSocket server. It manages pairing sessions and room/device state, validates device tokens and message limits, and forwards ciphertext. Read Pairing and sync for client behavior and Security and storage for keys and trust assumptions.
| Route | Purpose |
|---|---|
POST /v1/pairing/create |
Create a short-lived pairing session |
POST /v1/pairing/join |
Request to join using a code |
GET /v1/ws |
Upgrade to WebSocket; authenticate in the subsequent hello message |
GET /healthz |
Check process health |
GET /metrics |
Connection, forwarding, pairing, and expiry counters |
Rooms, pairing, membership, and queued text live in memory. A fixed token signing key does not restore room state lost on restart. Key rotation or state loss may require re-pairing. Persistent image/file storage and shared state across multiple relay instances are not part of the current implementation.
By default, server startup requires a TLS certificate and private key. To serve HTTPS/WSS directly, configure the following example paths and domain; they are placeholders, not production values:
export CLIPSYNC_RELAY_BIND=0.0.0.0:7600
export CLIPSYNC_RELAY_PUBLIC_URL=https://relay.example.com:7600
export CLIPSYNC_RELAY_TLS_CERT_FILE=/etc/clipsync/tls/fullchain.pem
export CLIPSYNC_RELAY_TLS_KEY_FILE=/etc/clipsync/tls/key.pem
clipsync-relayOnly TLS 1.2 and 1.3 are allowed. Supply both certificate and key; unreadable, oversized, or mismatched files prevent startup. Restart the server after replacing certificates. Clients using a private CA can add its public root PEM through CLIPSYNC_CA_FILE while retaining normal issuer and hostname verification.
For HTTP behind a TLS-terminating proxy, explicitly enable CLIPSYNC_RELAY_ALLOW_HTTP=true and restrict origin access to the proxy or local network. The root Compose example publishes only on host 127.0.0.1:7600 for local development.
docker compose upDistinguish the container's internal listener address from the host's published address. Public clients use the proxy's HTTPS URL. The existing Proxmox/Cloudflare Tunnel deployment resources are under deploy/proxmox/.
Supply the signing key through either CLIPSYNC_RELAY_TOKEN_SECRET or CLIPSYNC_RELAY_TOKEN_SECRET_FILE. An explicitly configured key must contain at least 32 bytes. If unset, a new key is generated with OS randomness. Webhooks require both a URL and a separate secret. Never record actual secret values in Git, the wiki, or public logs.
The server limits TLS handshakes to five seconds and 128 incomplete handshakes, and sets a deadline for the first HTTP request. HTTP/WS body limits and pairing/connection limits apply separately. Behind a proxy, the TCP peer is the proxy; forwarded-IP headers are not automatically promoted to trusted client addresses. Account for this behavior when designing traffic limits.
Use /healthz for health checks, /metrics for counters, and server logs for detailed diagnostics. On clients, clipsync doctor reports TLS, clipboard, service, and relay connectivity information; clipsync status reports daemon and connection state. A healthy endpoint alone does not establish successful end-to-end synchronization between two devices.
For deployment, permissions, and key rotation procedures, refer to the self-hosting guide, server transport implementation, HTTP router, and deployment directory.
Baseline: source 76c63f9 · 2026-11-16 · Wiki home · Source repository. The wiki is a separate Git repository and is not synchronized with product sources automatically.