clipbridge

clipbridge sends a macOS clipboard image through an existing SSH connection and pastes the remote PNG path into the active tmux pane. It is designed for Codex, Claude Code, OpenCode, Neovim, and other terminal applications that need a real file path rather than terminal image rendering.

The release binary is about 350 KB and has no third-party runtime dependencies.

How it works

1. A macOS launch agent runs clipbridge serve on laptop loopback port 57391.
2. OpenSSH reverse-forwards that loopback port to the remote Mac.
3. Cmd+Shift+V in Cmux sends a private terminal sequence recognized by tmux.
4. clipbridge paste fetches the PNG, writes it under ~/.cache/clipbridge, and inserts its path into the current pane.

The bridge binds only to loopback and requires a shared 256-bit token. Temporary and remote images are private (0700 directory, 0600 files), payloads are limited to 25 MB, and remote images older than seven days are removed after a successful paste.

Requirements

• macOS on the clipboard host and remote machine
• OpenSSH and tmux
• Rust 1.85 or newer to build
• Cmux, Ghostty, or another terminal that can map a shortcut to raw bytes

Install

If both Macs use the same CPU architecture, build once on the laptop and copy the single binary to both machines. Otherwise, run the build on each Mac.

cargo build --release
install -d "$HOME/.local/bin"
install -m 755 target/release/clipbridge "$HOME/.local/bin/clipbridge"
ssh remote-mac 'mkdir -p ~/.local/bin ~/.config/clipbridge ~/.cache/clipbridge && chmod 700 ~/.config/clipbridge ~/.cache/clipbridge'
scp target/release/clipbridge remote-mac:.local/bin/clipbridge
ssh remote-mac 'chmod 755 ~/.local/bin/clipbridge'

Generate one private shared token and copy it to the remote Mac:

install -d -m 700 "$HOME/.config/clipbridge"
(umask 077; openssl rand -hex 32 -out "$HOME/.config/clipbridge/token")
chmod 600 "$HOME/.config/clipbridge/token"
scp "$HOME/.config/clipbridge/token" remote-mac:.config/clipbridge/token
ssh remote-mac 'chmod 600 ~/.config/clipbridge/token'

Install the laptop launch agent. Replace __HOME__ in the example with the absolute value printed by printf '%s\n' "$HOME":

mkdir -p "$HOME/Library/LaunchAgents"
install -d -m 700 "$HOME/.cache/clipbridge"
install -m 600 /dev/null "$HOME/.cache/clipbridge/server.log"
sed "s|__HOME__|$HOME|g" config/com.example.clipbridge.plist \
  > "$HOME/Library/LaunchAgents/com.example.clipbridge.plist"
launchctl bootstrap "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/com.example.clipbridge.plist"

Merge config/ssh.conf into ~/.ssh/config, replacing remote-mac with your existing SSH alias. ExitOnForwardFailure makes SSH stop when it cannot establish the requested reverse forward, while OpenSSH connection sharing lets multiple terminal sessions reuse one authenticated forward.

SSH processes do not reread configuration after they start. After closing connections opened before adding the fragment, run ssh -O exit remote-mac (an absent-master error is harmless), then ssh remote-mac true so a fresh shared master establishes the reverse forward.

Merge config/tmux.conf into the remote ~/.tmux.conf, then reload it:

ssh remote-mac 'tmux source-file ~/.tmux.conf'

For Cmux or Ghostty, add this to ~/.config/ghostty/config and reload the terminal configuration:

keybind = super+shift+v=text:\x1b[99~

Use

1. Take a screenshot to the clipboard with Cmd+Ctrl+Shift+4.
2. Inside the remote tmux pane, press Cmd+Shift+V.
3. The private remote PNG path appears at the cursor.

Normal Cmd+V remains available for text.

Troubleshooting

Check that the shared SSH connection and reverse listener exist:

ssh -O check remote-mac
ssh remote-mac 'nc -z 127.0.0.1 57391'

If the clipboard contains text instead of an image, tmux displays a specific clipboard does not contain an image message. If the tunnel is absent, it displays clipboard tunnel is unavailable.

Security model

The token authenticates the remote client to the laptop service; it does not provide mutual server authentication. The design assumes processes running as your remote account are trusted. Before pasting, ensure the SSH master and reverse listener checks above pass. Do not invoke clipbridge paste after SSH setup or the listener check fails. Anyone who can read the token or impersonate the loopback listener from an already-open remote session can request clipboard images. Rotate the token if either machine or account is compromised.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release

License

MIT