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
What is this?ssh-clipboard syncs your clipboard across macOS and Linux machines over SSH: copy on one computer, paste on another, with text, images, files, and rich content kept in their native formats. There is no cloud component.
Does it live in a terminal, or does it drive the real system clipboard?It writes to the native clipboard—macOS pasteboard and Linux Wayland/X11—not terminal escape tricks. A per-user background service keeps peers in sync, and a Ratatui TUI handles first-run setup and the monitor.
How do I connect my machines?Run the first-run TUI: it offers compatible online machines discovered through Tailscale if you have it, or accepts any passwordless SSH connection. It verifies each connection, installs or upgrades only when needed, and starts a per-user background service.
What needs to be on my machines already?It is distributed via npm, so Node.js 18 or newer is required, plus passwordless SSH between peers; Tailscale is optional and only used for discovery. On Linux you also need a running graphical clipboard (X11 or a supported Wayland session).
Are there size or metadata limits on what I can copy?macOS-only metadata such as resource forks and extended attributes is not preserved, symlink transfers require both peers on the current version, and a default 256 MiB maxbytes cap applies to the whole selection—transfers are buffered in memory, so large files need a raised limit on both machines.
Will it work on a headless Linux server with no display?Yes—setup detects the missing display and offers an opt-in managed Xvfb service on private display :99. If Xvfb is not installed, it shows the right apt, dnf, or pacman command, and it never runs sudo without you.
Does my clipboard traffic pass through any third-party server?No—peers talk over persistent direct SSH connections using your existing SSH setup: no relay, no account, no port forwarding, and no new encryption key.
Can I copy files and folders between machines, not just text?Yes—copy in Finder or a Linux file manager, watch the transfer in ssh-clipboard monitor, then paste into a folder on the other machine. Transfers are extension-independent and preserve folders, empty directories, and executable permissions; copying never executes anything or deletes the source.
Will it clash with clipboard managers like Raycast?No—the service performs ordinary system clipboard writes, so Raycast and other clipboard managers just see normal clipboard activity.
How do updates reach every machine?Every installed daemon checks the stable npm release at startup and every 15 minutes and gossips its verified desired version to connected peers, so any online machine can trigger convergence—there is no permanent update coordinator. Updates pass npm SHA-512 and bundled SHA-256 manifest checks and swap the binary atomically while keeping the previous executable.
What about Linux desktop containers without systemd?The same executable supervises the daemon itself and restarts it after crashes or updates—no separate supervisor package. After a container restart, an incoming SSH clipboard connection revives an enabled service.
What are similar projects?tincan-cli, gyotaku, atuin, memex, sshdesk, syncthing, Telegram-Drive, kakoune
Which topics is it in?peer-to-peer, tailscale, clipboard, daemon, x11, wayland, sync, file-sharing, ssh, tui, encryption, rust
Creator
standardagents
Size
0.6 MB
Stars
244
Updated
CommitSep 09
Age
2mo
Commits · 90 Days