clipport

Paste Mac clipboard text, images, and screenshots into remote iTerm SSH sessions.

Clipport lets you share images and screenshots over SSH without saving files by hand or running one-off scp commands. One iTerm paste shortcut works across local and remote shells: Clipport detects the active session, reads the Mac clipboard, and chooses the right paste behavior.

If your Mac clipboard has text, the remote shell receives text. If it has an image or screenshot, Clipport uploads it over SSH and inserts the remote path.

Session	Clipboard	Terminal receives
local	text, image, or screenshot	native paste; clipctl paste prints nothing
remote	text	clipboard text
remote	screenshot or image	remote file path under /tmp/clipport/...

Demo

Remote image or screenshot example:

/tmp/clipport/yourname/clipboard-20260428-132708.241851.png

Use Clipport when a remote process needs the thing on your Mac clipboard: a screenshot, an image, or plain text pasted through the same terminal shortcut.

Use Cases

Clipport is useful when the remote shell needs local clipboard state:

• paste a screenshot path into a VM shell
• hand a local image to a remote command
• avoid one-off scp for screenshots and clipboard images
• keep one paste shortcut for local and SSH shells

Requirements

• macOS
• iTerm2
• Homebrew
• passwordless SSH to each remote machine
• writable /tmp on each remote machine

Quick Start

brew install arihantsethia/tap/clipport
clipctl onboard
clipctl start
clipctl doctor

Then open an SSH session in iTerm, copy text, an image, or a screenshot on your Mac, and press the Clipport paste shortcut.

Install

brew install arihantsethia/tap/clipport

Homebrew installs clipctl, clipportd, and the Clipport menu bar app. clipctl onboard records the local app paths in ~/.config/clipport/config.toml before configuring SSH routes.

Manual install without Homebrew tap:

curl -fsSL https://raw.githubusercontent.com/arihantsethia/clipport/main/install.sh | sh

Setup

Build host config from ~/.ssh/config:

clipctl onboard

Onboarding lets you choose SSH hosts, configure the iTerm paste shortcut, and install OpenSSH LocalCommand hooks for automatic session matching.

Start Clipport:

clipctl start

Check the install:

clipctl doctor

Then open an SSH session in iTerm, copy text on your Mac, and press the Clipport paste shortcut. Text should appear at the remote prompt.

For images and screenshots, copy the clipboard item and press the same shortcut. The remote prompt receives a path like:

/tmp/clipport/yourname/clipboard-20260428-132708.241851.png

Test remote image upload without changing your clipboard:

clipctl test-paste --host <machine>

Behavior

iTerm runs this command behind the paste shortcut:

clipctl paste

Stdout is strict because iTerm inserts stdout into the terminal:

• local paste prints nothing
• remote text prints the clipboard text
• remote image upload prints only the remote path

Remote uploads always use paths under:

/tmp/clipport/<local-user>/

Configuration

A machine is one remote filesystem. A route is one SSH path to that machine. OpenSSH still owns aliases, keys, proxies, and connection behavior.

Rerun onboarding:

clipctl onboard

List SSH hosts seen by onboarding:

clipctl onboard --list

Local install settings and host routes live in:

~/.config/clipport/config.toml

The file contains no secrets.

Session Matching

Clipport maps the active iTerm session to a configured machine. OpenSSH LocalCommand hooks make that mapping explicit. If hooks are not installed or do not fire, terminal title detection and manual registration remain available.

Register the current iTerm session manually:

clipctl session register --machine <machine>

Show configured hosts, registered sessions, and recent transfers:

clipctl status

Menu Bar

When started, the menu bar app supervises clipportd. It shows daemon health, configured hosts, and shortcuts to restart Clipport, run clipctl doctor, and open config or log files.

clipportd exits when the menu bar app exits. Choosing Quit stops the daemon and exits Clipport. The menu bar app does not change the clipctl paste stdout contract.

Commands

# Paste entrypoint used by iTerm.
clipctl paste

# Start, stop, or restart the menu bar app and daemon.
clipctl start
clipctl stop
clipctl restart

# Health check.
clipctl doctor

# Status and recent transfers.
clipctl status

# Upload an embedded test PNG to a configured machine.
clipctl test-paste --host <machine>

# Update from the public installer source.
clipctl update

Debug paste failures:

clipctl --debug paste

Remote Clipboard Shims

Shims are only for remote programs that call wl-paste or xclip directly.

Install shims for a configured machine:

clipctl shims setup --host <machine>

Both local and remote tokens live at:

~/.config/clipport/token

Permissions are 0600. Tokens are not embedded in executable scripts. The local HTTP endpoint binds only to loopback.

Remove shims:

clipctl shims uninstall --host <machine>

Remove the remote token too:

clipctl shims uninstall --host <machine> --remove-remote-token

Install Options

From a checkout:

./install.sh

Install binaries somewhere else:

CLIPPORT_BIN=/some/bin ./install.sh

Use a different iTerm key binding:

CLIPPORT_ITERM_KEY=<iterm-key-code> ./install.sh

Use a specific loopback HTTP address:

CLIPPORT_HTTP=127.0.0.1:18800 ./install.sh

Update

clipctl update

clipctl update downloads the latest installer and applies it using the current install settings.

Set CLIPPORT_REF to update from another branch or ref:

CLIPPORT_REF=<ref> clipctl update

Uninstall

clipctl uninstall

Preview:

clipctl uninstall --dry-run

Remove local config, cache, token, and /tmp/clipport files:

clipctl uninstall --remove-data

By default, uninstall keeps local data and remote shim tokens.

Troubleshooting

Start with:

clipctl doctor

Common cases:

• LAN route fails: expected when off that network; Clipport tries the next route.
• SSH shell gets native paste: run clipctl session register --machine <machine> in that iTerm session.
• Hotkey does nothing: confirm iTerm runs clipctl paste, then check /tmp/clipportd.err.log.
• Image upload fails: check passwordless SSH and remote write access to /tmp/clipport.

Development

gofmt -w <changed go files>
go test ./...
go vet ./...
go build ./cmd/clipctl ./cmd/clipportd
CGO_ENABLED=1 go build -o /tmp/clipport-check ./cmd/clipport

See ARCHITECTURE.md for the contributor architecture map. Report security issues using SECURITY.md.

License

Clipport is released under the MIT License.