ssh-clipboard README

The project's README from github.com/standardagents/ssh-clipboard. As one markdown file: README.md.

ssh-clipboard

Your clipboard. Every machine. No cloud.

CI npm MIT

┌──────────────┐        encrypted SSH        ┌──────────────┐
│   your Mac   │  ◀══════════════════════▶  │  Mac / Linux │
└──────────────┘                             └──────────────┘

Copy here. Paste there. Text, images, files, rich content—native formats intact.

npm i -g ssh-clipboard
ssh-clipboard

The first-run TUI offers compatible online machines from Tailscale when it is installed, or accepts any passwordless SSH connection. It verifies each connection, inspects any existing installation, installs or upgrades only when needed, and starts a per-user background service without replacing that machine’s identity or peer configuration. After that, it just feels like one clipboard.

ssh-clipboard monitor          # delightful live dashboard
ssh-clipboard status --json    # automation-friendly health
ssh-clipboard setup            # add or repair peers
ssh-clipboard update --check   # compare this node with npm @latest

The manual update command also reconciles the per-user service, so it can recover an installed binary whose launchd or systemd job is missing.

Copying files

Copy files or folders in Finder or a Linux file manager, wait for the transfer to finish in ssh-clipboard monitor, then paste into a folder on the other machine. Transfers work in both directions and are extension-independent: PDFs, DMGs, PKGs, images, documents, and unknown file types all use the same byte-transfer path. Folders, empty directories, executable permissions, and symbolic links are preserved. Copying does not install or execute anything, and does not delete the source.

On Linux, a running graphical clipboard (X11 or supported Wayland session) is required. The receiver publishes local file URLs with the shared URI-list, GNOME/Nautilus (also used by Thunar), and KDE copy formats. X11 transfers use incremental delivery for large clipboard representations, inside the existing daemon; no sidecar is required. Live Thunar transfers and independent GTK protocol tests cover both directions; this is shared-format support, not a claim that every file-manager version was UI-tested. Raw image clipboards (for example, screenshots copied without saving a file) also offer a cached image file on Linux. PNG is preferred when available; the original image representations remain available for pasting into image editors. Identical image bytes reuse the same private cache file instead of creating repeated copies. macOS applications and installers remain files, not Linux-compatible applications. macOS-only metadata such as resource forks and extended attributes is not currently preserved. Both peers must run the current version for symbolic-link transfers.

The configured max_bytes limit applies to the whole selection, including transfer metadata (256 MiB by default). Larger selections require raising it on both peers and restarting their services. Transfers are currently buffered in memory, so choose a limit that both machines can accommodate; large files are not instantaneous.

When using Apple's Screen Sharing, turn off Edit → Use Shared Clipboard to avoid its separate filename-only clipboard updates competing with ssh-clipboard.

Headless Linux

Linux servers without Wayland or X11 need a virtual display before they have a clipboard. ssh-clipboard setup detects this condition and offers an opt-in managed Xvfb service. If Xvfb is not installed, setup shows the appropriate apt, dnf, or pacman command; it never runs sudo without you. Once selected, the per-user service runs against private display :99 and upgrades preserve that choice. See the headless Linux guide for guided and manual setup, lingering, and troubleshooting.

Linux desktop containers

Without systemd, the same ssh-clipboard executable supervises the daemon and restarts it after crashes or updates. No separate supervisor package is needed. Run ssh-clipboard service install --native-display in the container's desktop terminal to select that desktop; its display environment is saved for subsequent SSH sessions and updates. A private --headless-x11 display does not share an existing VNC desktop's clipboard. When installing over SSH, explicitly supply that desktop's DISPLAY and, if needed, XAUTHORITY (or its Wayland environment).

Only one side needs to initiate SSH; an established connection carries clipboard data in both directions. Add the container as a peer on the Mac that can SSH into it. service start, service stop, service restart, and the normal monitor still work. After a container restart, an incoming SSH clipboard connection revives an enabled service. Without an incoming connection, invoke ssh-clipboard service start from the container's startup hook. An explicit stop disables automatic revival. Recreating a container requires retaining its binary, configuration, and state directories or reinstalling.

The monitor shows each machine on its own row with installed and target versions. Press u to queue an immediate npm check and notify every connected client that supports update events.

Every installed daemon independently checks the stable npm release at startup and every 15 minutes, and gossips its verified desired version to connected peers. Any online machine can therefore trigger convergence; there is no permanent update coordinator. Packages are accepted only after npm SHA-512 integrity, the bundled SHA-256 manifest, executable target, and reported binary version all agree. Updates retain the previous executable, replace the live binary atomically, and explicitly ask launchd/systemd to restart the daemon.

macOS and Linux · arm64 and x64 · Rust + Ratatui

Deep cuts: architecture · headless Linux · TUI design · npm distribution

ssh-clipboard (standardagents/ssh-clipboard)

Searching Database…

244 ·GitHub
Ssh-clipboard
这是什么?ssh-clipboard 通过 SSH 在 macOS 和 Linux 机器之间同步剪贴板:在一台电脑上复制,在另一台上粘贴,文本、图片、文件和富内容都会以原始格式保留。它没有任何云端组件。
它是运行在终端里的,还是直接操作系统的真实剪贴板?它写入的是系统原生剪贴板——macOS 的 pasteboard 和 Linux 的 Wayland/X11——而不是终端转义字符的花招。一个按用户运行的后台服务负责让各台机器保持同步,Ratatui TUI 则负责首次设置和监控界面。
我该怎么把我的机器连接起来?运行首次启动的 TUI:如果你装了 Tailscale,它会列出通过 Tailscale 发现的兼容在线机器供你选择,也接受任何免密码的 SSH 连接。它会验证每一个连接,只在需要时才安装或升级,并启动一个按用户运行的后台服务。
我的机器上需要提前装好什么?它通过 npm 分发,所以需要 Node.js 18 或更高版本,机器之间还需要免密码的 SSH;Tailscale 是可选的,只用来发现设备。在 Linux 上,你还需要一个正在运行的图形化剪贴板(X11 或受支持的 Wayland 会话)。
复制的内容在大小或元数据上有什么限制吗?macOS 特有的元数据(例如 resource fork 和扩展属性)不会被保留;传输符号链接要求两端都是当前版本;整个选择内容默认有 256 MiB 的 maxbytes 上限——传输是在内存中缓冲的,所以传大文件需要在两台机器上都调高这个限制。
在没有显示器的无界面 Linux 服务器上能用吗?可以——安装程序会检测到缺少显示器,并提供一个可选的托管 Xvfb 服务,运行在私有显示 :99 上。如果 Xvfb 没有安装,它会给出对应的 apt、dnf 或 pacman 命令,而且未经你同意绝不会执行 sudo。
我的剪贴板数据会经过任何第三方服务器吗?不会——各台机器通过持久的直连 SSH 通信,用的是你现有的 SSH 配置:没有中继、没有账号、不需要端口转发,也不会生成新的加密密钥。
我能在机器之间复制文件和文件夹吗,不只是文本?可以——在 Finder 或 Linux 文件管理器里复制,在 ssh-clipboard monitor 中查看传输进度,然后粘贴到另一台机器的文件夹里。传输与文件扩展名无关,会保留文件夹结构、空目录和可执行权限;复制过程不会执行任何内容,也不会删除源文件。
它会和 Raycast 之类的剪贴板管理工具冲突吗?不会——这个服务执行的只是普通的系统剪贴板写入操作,所以 Raycast 和其他剪贴板管理工具只会把它当成正常的剪贴板活动。
更新是怎么到达每一台机器的?每个已安装的守护进程都会在启动时和之后每 15 分钟检查一次 npm 上的稳定版本,并把验证过的目标版本告知已连接的其他机器,因此任何一台在线机器都能触发同步收敛——没有常驻的更新协调节点。更新会通过 npm 的 SHA-512 和内置的 SHA-256 清单校验,并原子地替换二进制文件,同时保留上一个可执行文件。
那没有 systemd 的 Linux 桌面容器呢?同一个可执行文件会自己监督守护进程,在崩溃或更新后将其重启——不需要单独的监督程序包。容器重启之后,只要有一条传入的 SSH 剪贴板连接,已启用的服务就会自动恢复运行。
What are similar projects?tincan-cli, gyotaku, atuin, memex, reason-network, sshdesk, syncthing, Telegram-Drive
Which topics is it in?peer-to-peer, tailscale, clipboard, daemon, x11, wayland, file-sharing, sync, ssh, tui, encryption, rust
Creator
standardagents
Size
0.6 MB
Stars
244
Updated
CommitSep 09
Age
2mo
Commits · 90 Days