Skip to content

Relay Operations

develicit edited this page Nov 16, 2026 · 2 revisions

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.

Network boundary

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.

TLS deployment

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-relay

Only 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 up

Distinguish 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/.

Secrets and limits

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.

Observability and troubleshooting

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.

Clone this wiki locally