Omahub
← All plugins
A

iPhone Clipboard Bridge

by Aaron K. Hawkins

Copy text, one or many photos, and files on an iPhone and paste them directly into Omarchy through Tailscale.

GitHub Homepage

Security review

Review recommended · 7 findings

Deterministic scan — not a security guarantee

Medium
Risk level
Medium
Analyzed commit
12bbf9e
Scanned
1 month ago
  • medium package_manager …/workflows/ci.yml:18

    System package manager operation.

    apt-get install -y imagemagick jq shellcheck
  • medium sudo …/workflows/ci.yml:18

    Command runs with sudo, elevating the process beyond the plugin environment.

    sudo apt-get install -y imagemagick jq shellcheck
  • low obfuscation receiver.py:45

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n")),
  • low obfuscation tests/test_receiver.py:146

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n" + source.read_bytes())
  • low obfuscation tests/test_receiver.py:218

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n": "image/png",
  • low obfuscation tests/test_receiver.py:396

    Augments a command with octal/hex escape sequences.

    \x89PNG\r\n\x1a\n",
  • Docs external_hosts README.md:141

    Downloads or connects to an external HTTP(S) host.

    curl https://YOUR-MACHINE.YOUR-TAILNET.ts.net/clipboard

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
12bbf9e
Reviewed
1 month ago

The plugin is a well-engineered local clipboard bridge that binds to 127.0.0.1, requires a bearer token, and uses Tailscale Serve for authenticated tailnet-only access. The deterministic scan's medium findings are all benign: the README curl example is documentation, the hex escapes are PNG magic bytes, and the CI sudo/apt-get are test-environment operations. No obfuscated or destructive code was found in the executable paths.

  • The setup.sh script modifies Tailscale Serve configuration and creates a token file; this is user-initiated and clearly documented, but it does change system networking state.
  • Anyone with both tailnet access and the bearer token can replace the desktop clipboard; this is an inherent design tradeoff and is disclosed in the README.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/aaronkhawkins/omarchy-iphone-clipboard --enable
Productivity #quickshell #system

iPhone Clipboard Bridge for Omarchy

Copy text, photos, or files on an iPhone, trigger an Apple Shortcut, and paste the item normally in Omarchy. Transfers use a private, authenticated Tailscale Serve route—no cloud clipboard account or public internet endpoint.

Requirements

  • Omarchy 4+
  • Tailscale connected on both the iPhone and Omarchy machine
  • python3, wl-copy, notify-send, ImageMagick (magick), tailscale, jq, and ss

On Omarchy, install any missing packages before setup:

omarchy pkg add python wl-clipboard libnotify imagemagick tailscale jq iproute2

Omarchy plugins do not run install hooks, so setup.sh is a required manual step on each new machine.

Install

Add the plugin without enabling it, run setup, and then enable it:

omarchy plugin add https://github.com/aaronkhawkins/omarchy-iphone-clipboard.git
~/.config/omarchy/plugins/io.github.aaronkhawkins.iphone-clipboard/setup.sh
omarchy plugin enable io.github.aaronkhawkins.iphone-clipboard

Setup checks dependencies, refuses to reuse a port or Tailscale route owned by another program, creates a private bearer token, and configures only the /clipboard Tailscale Serve path. It prints the URL and authorization header needed by the iPhone Shortcut.

iPhone Shortcut

Create a shortcut named Send Clipboard to Framework. This final layout works from Back Tap and from the Photos Share Sheet:

  1. Open the Shortcut's details and enable Show in Share Sheet. In the Receive … input from Share Sheet row, accept Images and Files, set the no-input behavior to Continue, and turn off Get What's On Screen.
  2. Add If Shortcut Input has any value.
    • Inside If, use Set Variable to set Transfer Items to Shortcut Input.
    • Inside Otherwise, add Get Clipboard, then set Transfer Items to the Clipboard result.
  3. After End If, add URL using the URL printed by setup.sh. Keep this action above and outside the remaining If and Repeat actions.
  4. Add Count, choose Items, and count Transfer Items.
  5. Add If Count is greater than 1.
    • Add Random Number and set its range to 100000000–999999999.
    • Add Repeat with Each using Transfer Items.
    • Inside Repeat, add Get Contents of URL. Select the earlier URL magic variable, set Method to POST, Request Body to File, and File to Repeat Item. Add these headers:
      • Authorization: the complete Bearer … value printed by setup
      • X-Clipboard-Batch-ID: Random Number
      • X-Clipboard-Item-Index: Repeat Index
      • X-Clipboard-Item-Count: Count
  6. Inside Otherwise, add one Get Contents of URL action using the earlier URL. Set Method to POST, Request Body to File, File to Transfer Items, and add only the Authorization header.
  7. Finish with End If. If upgrading the old one-item Shortcut, move its POST into Otherwise; do not leave a second POST outside the branch.

For example, if setup prints:

Name:  Authorization
Value: Bearer abc123

enter Authorization as the header name and Bearer abc123 as its value. Include the word Bearer, one space, and the entire token. Do not enter only abc123, and do not add quotation marks. Use the real value printed on your machine rather than this example.

Run it once and approve the network and clipboard prompts. For one-gesture use, assign it under Settings → Accessibility → Touch → Back Tap, or to the iPhone Action Button. For several photos, select them in Photos and choose Share → Send Clipboard to Framework. Back Tap also handles several copied items when iOS exposes them as a list; temporarily use Quick Look after Get Clipboard if you want to verify what that iOS version provides.

The receiver accepts 2–32 batch items and updates the clipboard only after all items arrive. Multiple photos paste as files because Wayland represents a multi-file clipboard as text/uri-list; one photo continues to paste directly as an image.

To print the existing URL and token again, rerun setup.sh. The token remains unchanged unless its file is removed.

Behavior

  • Text is placed directly in the Wayland clipboard.
  • JPEG, HEIC, GIF, TIFF, and WebP photos are validated and converted to PNG because many Wayland applications accept pasted images only as image/png.
  • PDFs, archives, and other file-like items are retained under ~/.local/state/iphone-clipboard/items/ and exposed as a pasteable file.
  • The input limit is 1 GiB. Large compressed images can require additional temporary disk and memory during conversion.
  • Retained files are capped at 10 GiB and 4,096 files total. Transfers and image conversions are rejected before they would leave less than 2 GiB free. Upload staging and retained-file commits also require at least 1,024 free filesystem entries. Rejection is used instead of eviction so existing clipboard-history file links are not silently broken.
  • Transfers are processed one at a time.
  • Text, photos, and files appear in Omarchy's native clipboard history. Open it with Super + Ctrl + V. File payloads use content-addressed names and remain available so older history entries do not break.
  • Fresh multi-file paste works in apps that accept pasted files or file URI lists. Apps that accept only one image/png may not accept several photos at once. Omarchy currently recalls a multi-file history row as plain URI text, so use the freshly received entry for multi-file paste; this is an upstream clipboard-history limitation.

Security and privacy

The receiver listens only on 127.0.0.1; Tailscale Serve provides tailnet-only HTTPS access at /clipboard. POST requests also require the random bearer token stored with mode 0600 at ~/.local/state/iphone-clipboard/token. Clipboard contents are not logged. Anyone who has both network access to the Serve route and this token can replace the desktop clipboard, so do not share the token.

The health-check GET endpoint intentionally returns only status and the maximum payload size. Incoming image formats are signature-checked before ImageMagick is used, conversion resources are bounded, and upload processing is serialized. Setup refuses symlinked token/state paths and creates a new token through an exclusive, no-follow file descriptor. Multi-item batches are bounded and staged privately; an incomplete batch never replaces the current clipboard.

Troubleshooting

omarchy plugin list
tailscale serve status
curl https://YOUR-MACHINE.YOUR-TAILNET.ts.net/clipboard
ss -ltn 'sport = :8787'
  • If Safari can open the URL but POST returns Unauthorized, copy the complete Bearer … value from setup.sh into the Shortcut's Authorization header.
  • If nothing listens on port 8787, rerun setup, then disable and enable the plugin. Startup retries are bounded so a configuration error cannot create a permanent crash loop.
  • Confirm Tailscale is connected on both devices and that tailnet policy permits the iPhone to reach the Omarchy machine.

Remove

Disable the plugin, remove only its Tailscale route, and then remove the plugin:

omarchy plugin disable io.github.aaronkhawkins.iphone-clipboard
~/.config/omarchy/plugins/io.github.aaronkhawkins.iphone-clipboard/remove-route.sh
omarchy plugin remove io.github.aaronkhawkins.iphone-clipboard

Received files and the token are deliberately retained, including files still referenced by clipboard history. To remove them too (old file history rows will no longer open):

gio trash ~/.local/state/iphone-clipboard

License

MIT © Aaron K. Hawkins