deploy-lan-clipboard-sync

name	deploy-lan-clipboard-sync
description	Deploy or repair private bidirectional text clipboard synchronization between desktop macOS, Windows, and Linux devices on a trusted LAN. Use when a user gives this repository link and asks an agent to install, configure, restore, pair, autostart, or verify LAN clipboard sync, including requests such as "deploy this link", "帮我部署局域网剪贴板同步", or "同步断了，恢复它".

Deploy LAN Clipboard Sync

What it does

This skill teaches an AI coding agent how to connect the text clipboards of two computers on the same local network. Copy text on one computer and it becomes available to paste on the other, in both directions. The agent handles setup, pairing, automatic startup, security checks, and testing on macOS, Windows, or Linux. Nothing is sent through a cloud service.

Make the requested machines work end to end. Do not merely provide commands. Keep all generated runtime code, addresses, device names, tokens, and logs outside this skill repository.

Establish scope

1. Detect the OS, interactive desktop session, current LAN address, default gateway, proxy/VPN environment, available runtime, and clipboard commands. Identify a trusted LAN by interface, gateway, or SSID; never require the machine to keep one exact DHCP address.
2. Confirm whether this is the first node, a joining node, or a repair. If only one machine is in scope, do not modify the other machine.
3. Inspect existing listeners, processes, startup entries, and configuration before writing. Preserve unrelated services and reuse a healthy owned install.
4. Use a configurable port, defaulting to 8765. Never stop an unrelated process to claim that port.

Build the local node

Generate a small symmetric node using an available maintained runtime; prefer Python 3.10+ and its standard library. Run the same server and watcher design on both devices.

Implement these invariants:

• Synchronize text only; cap UTF-8 payloads at 512 KiB.
• Expose GET /health without secrets and include a protocol version. Require X-Token for clipboard state, history, updates, and pairing. Refuse an incompatible peer before replacing config or enabling startup.
• Generate at least 32 random bytes for the shared token. Compare tokens with a constant-time function when available.
• Bind only to the trusted LAN interface when reliable. Otherwise bind IPv4 and reject non-loopback, non-private source addresses before authentication.
• Disable clipboard history and remote empty-text writes by default. Cap request concurrency, queue length, body size, and socket duration before exposing the service to the LAN.
• Send LAN requests through a proxy-free client and configure NO_PROXY for loopback, the local subnet, and the peer. Do not disable the user's VPN.
• Establish the watcher baseline without sending clipboard text that existed before startup. Prefer an OS clipboard-change notification or sequence counter; do not repeatedly open the Windows clipboard merely to detect a change.
• Keep only the newest failed outbound text pending. Use request timeouts and bounded exponential backoff, reaching no more than one retry every 30 seconds. Apply the same backoff to local clipboard read failures.
• Allow only one inbound clipboard write at a time, suppress immediate duplicate writes, and open a cooldown circuit after repeated native clipboard failures. Remote writes must not create an echo loop.
• Persist the peer URL through an authenticated pairing operation. Normalize and validate it; accept only HTTP endpoints on private or loopback addresses.
• Store a stable random device ID separately from its current network address. Treat addresses as replaceable discovery results, not device identity.
• Return minimal errors. Never include tokens, clipboard text, home paths, or full peer configuration in health responses or routine logs.

Use the native clipboard backend:

• macOS: pbpaste and pbcopy.
• Windows: PowerShell Get-Clipboard -Raw and Set-Clipboard; force UTF-8 for stdin, stdout, and JSON. Run in the interactive user's session.
• Linux Wayland: wl-paste and wl-copy.
• Linux X11: xclip or xsel.

Install a missing Linux clipboard utility with the detected package manager only after obtaining approval for elevated package installation. Stop with an actionable explanation if no desktop clipboard is available.

Store runtime state

Use an owned runtime directory and a private config file:

• macOS: ~/Library/Application Support/LANClipboardSync/
• Windows: %LOCALAPPDATA%\LANClipboardSync\
• Linux: ~/.local/share/lan-clipboard-sync/

Mark ownership with a small manifest containing the skill name and runtime version. Refuse to overwrite or uninstall paths/startup entries without that marker. Preserve a valid existing token during repair or upgrade. Write config atomically; use mode 0600 on POSIX and current-user-only ACLs on Windows.

Never put secrets in process arguments, repository files, shell history, Scheduled Tasks, or world-readable logs. Accept a joining token through a private prompt, protected temporary file, or process environment, then remove the temporary material.

Register current-user startup

• macOS: install one LaunchAgent under ~/Library/LaunchAgents/; run from the Application Support directory, enable restart on failure, and verify with launchctl print plus the health endpoint.
• Windows: use the current user's Startup folder or another current-user interactive-session mechanism. Do not use an elevated Scheduled Task for clipboard access. Record the exact child PID so uninstall can stop only the owned process.
• Linux: prefer a user service tied to the graphical session; otherwise use an XDG autostart entry. Preserve DISPLAY, WAYLAND_DISPLAY, and XDG_RUNTIME_DIR. Verify after a fresh process start.

Make installation idempotent. Stage new config separately, validate ownership and peer authentication, then replace the active config. Roll back if startup, health, or pairing fails.

Supervise the server and watcher as one process group. If either child exits, stop the surviving child before restarting the group so duplicate watchers cannot accumulate. Rotate owned logs at a small fixed size and retain at most one backup.

Pair devices

For the first node, start server-only, display its reachable private LAN URL, and privately hand off the token. Do not publish or commit the handoff.

For the joining node:

1. Verify the first node's /health directly without a proxy.
2. Authenticate with the supplied token before replacing any working config.
3. Start the joining node and verify its local /health.
4. Register the joining node's private LAN URL on the first node through the authenticated pairing endpoint.
5. Confirm both nodes report a configured peer without exposing the peer URL.

Treat step 4 as a remote configuration change. Skip it when the first node is outside the user's authorized scope; report the remaining one-way limitation and request explicit authorization instead of silently changing the remote node.

Resolve peer addresses in this order:

1. Prefer a tested .local hostname when it resolves reliably from both devices.
2. Otherwise add lightweight LAN discovery. Announce only the random device ID, service port, and protocol version over the current private interface. Never announce the token, clipboard content, username, hostname, or home path.
3. Authenticate every discovered candidate with the shared token before saving its new address or sending clipboard data.
4. Refresh discovery after network changes and repeated reachability failures so DHCP address changes recover without reinstalling.
5. Use a raw private IP only as a temporary fallback. Offer a router DHCP reservation as an optional optimization, never as a deployment requirement.

Limit discovery to the current private subnet, ignore public and VPN candidates, rate-limit announcements, and do not sweep every address in the subnet. Do not hard-code one user's subnet into reusable files.

Verify before finishing

Prove all of the following with runtime evidence:

• Owned startup entry is loaded and the expected process is running.
• Only the intended port is listening and /health responds directly.
• Peer port is reachable with proxy bypass.
• Mac/Windows/Linux A to B transfers a unique non-ASCII text value.
• B to A transfers a different unique non-ASCII text value.
• A failed push remains pending and succeeds after connectivity returns.
• Restarting the user-level service preserves pairing and restores sync.
• Repository and generated handoff contain no real token or private machine information.

Restore the user's original clipboard after testing when practical. Report the runtime location, startup mechanism, local URL, peer reachability, and both direction results. Never print the token in the final response.

Repair and uninstall

During repair, diagnose in this order: current LAN identity, owned startup state, child processes, listener, direct peer health, proxy bypass, authentication, then clipboard encoding. Update stale machine-local addresses without changing the other device unless it is explicitly in scope.

During uninstall, stop only the recorded owned PID/service, remove only the owned startup entry, and preserve config by default. Delete config and logs only when the user explicitly requests purge.

License

MIT License. Copyright (c) 2026 LAN Clipboard Sync contributors.

Permission is hereby granted, free of charge, to any person obtaining a copy of this document to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies, provided that this notice is included in substantial copies. The document is provided "AS IS", without warranty of any kind; the authors are not liable for claims or damages arising from its use.