Getting started with FainLane

When you run a CLI coding agent on a remote machine over SSH or mosh, the agent cannot directly access your Mac’s clipboard. Copying a screenshot on your Mac does not make it available on the remote machine. To share it with the agent, you would otherwise need to save the image, upload it, and provide its remote path in the agent session.

FainLane handles those steps from your Mac’s menu bar. Copy an image, focus your remote agent’s input in Ghostty, iTerm2, or Terminal.app, and press Control+V. FainLane uploads the image over SSH to the machine you are connected to and inserts the uploaded file’s path into the input. You can then add your instructions and send the message yourself.

Images are saved in ~/.cache/fainlane/uploads/ under your remote user’s home directory.

• Local agents: Image paste continues to work as usual when your agent runs locally on your Mac.
• tmux: Works with tmux on your Mac, on the remote server, or both.
• Multiple remote machines: FainLane detects the connection in your focused terminal session and uploads to that machine. You do not need to select a destination in the app.
• Multiple monitors: Use your terminal across multiple displays. The paste status appears on the display containing the focused terminal.

1. Check your Mac

Open Apple menu → About This Mac. You need:

• An Apple silicon Mac (M1 or later)
• macOS 15.7 or later

2. Update your terminal

Use one of these terminals:

Ghostty

FainLane requires the latest prerelease of Ghostty. The latest stable build doesn’t have the features we need to make this app work.

1. Open your Ghostty configuration and add this line:

   Configuration

   auto-update-channel = tip

2. Quit and reopen Ghostty.

3. Choose Ghostty → Check for Updates… and install the update.

See Ghostty’s prerelease instructions for details and installation options.

iTerm2

Update to the latest stable version of iTerm2.

Terminal.app

Use the Terminal app included with macOS. No separate update is needed.

3. Check your remote connection

SSH

From a normal shell in your Mac’s terminal, connect using either form:

ssh my-server
ssh user@host

Replace my-server with your SSH alias, or user@host with your remote username and hostname. Use the SSH client included with macOS. Put custom ports, keys, and jump-host settings in ~/.ssh/config so your connection command stays this simple.

FainLane needs to connect over SSH without asking for a password, key passphrase, or confirmation.

Optionally you can run a connection check from a separate local terminal tab:

/usr/bin/ssh -o BatchMode=yes -o StrictHostKeyChecking=yes \
  -o ControlMaster=no -o ControlPath=none -o RemoteCommand=none \
  -T my-server 'printf "SSH ready\n"'

Change my-server in the above command to use the same destination you connect to. The command should print SSH ready and exit without a prompt.

If it fails, check your network or VPN and SSH key setup. For a new server, connect normally first and verify its host-key fingerprint with your server administrator before accepting it. Keep host-key checking enabled. If your key is available only through your terminal’s environment, configure IdentityFile or IdentityAgent in ~/.ssh/config so FainLane can also use it.

Mosh

Use mosh 1.4 or later with a plain connection command:

mosh my-server
mosh user@host

Images still upload over SSH. The SSH check above must pass for the same destination, and SSH must remain reachable while you use mosh.

4. Install FainLane and grant permissions

1. Download FainLane from fainlane.com.
2. Open the DMG and drag FainLane into Applications.
3. Open FainLane from Applications. It runs in the menu bar under FL.
4. Follow the setup window and select your terminal. Keep that terminal open while granting permissions.

Setup walks you through three permissions:

Return to setup after granting access. If you close it, choose FL → Resume Setup. Permissions are also available under FL → Settings → Permissions.

5. Paste your first image

1. Connect to your remote machine and start your coding agent. Use an agent like Codex, Claude Code, OpenCode, or Pi with a model that can read images.
2. On your Mac, press Control+Shift+Command+4 and select a small area containing recognizable text. This copies a screenshot to the clipboard.
3. Focus the remote agent’s message input and press Control+V.
4. Wait for the uploaded image’s path to appear. Keep the terminal and pane focused while it uploads.
5. Add a request such as “Read this image and tell me what text it contains.” Send the message yourself. Allow the agent to read the file if it asks.

Check that the agent describes the image correctly. A path appearing in the input confirms neither that you sent the message nor that the agent read the image.

Return to setup to finish and choose whether FainLane should launch at login. Keep FainLane open when you want to use it.

If the first paste does not work

• Nothing happens: Check FL → Settings → Permissions and focus the agent’s input. Use Control+V with an image copied to the clipboard; copying a file in Finder is different. If permissions are ready, reopen FainLane or use Keyboard troubleshooting on the Permissions page.
• The upload fails: Open FL → Last Paste Status, then repeat the SSH check from step 3.
• The agent cannot read the image: Check that it runs on the original remote machine and user account, has permission to read the file, and uses a model that supports images.

Images stay on the remote machine until you delete them. Clearing FainLane’s local data does not remove remote files.