setup guide

Get filefling working.

filefling sends files from your Mac to a remote AI coding machine using SSH/SFTP. If you can SSH into the server, you can usually get filefling working in a few minutes.

Download Markdown docs .md Agent guide

Prefer plain text? Agents and humans can use /docs.md and /llms.txt.

Getting started

Step-by-step setup

Beta download available. The current macOS build is an unsigned Apple silicon ZIP. Download it from the homepage, then approve the first launch if Gatekeeper prompts. Download beta

Before you start

  • A Mac running filefling
  • A server reachable over SSH
  • An SSH username
  • A private key on your Mac
  • A writable folder on the server
  • Optional: hosts in ~/.ssh/config
01

Install filefling

Download the macOS beta ZIP, unzip it, and move filefling into Applications. Launch it from Applications; it will appear in your menubar. The current beta is unsigned, so macOS Gatekeeper may ask you to approve the first launch.

02

Make sure SSH works from your Mac

filefling uses your existing SSH access. Before configuring the app, confirm that you can connect to the destination manually.

ssh your-user@your-host
03

Use an existing SSH config host, or enter details manually

If your server is already in ~/.ssh/config, choose that host during setup to fill HostName, User, Port, and IdentityFile. Otherwise enter the values by hand.

Host devbox
  HostName 100.64.1.2
  User brad
  Port 22
  IdentityFile ~/.ssh/id_ed25519
04

Choose the remote upload directory

Pick the folder where screenshots and files should land. filefling can create it during the connection test if your SSH user has permission.

~/shared
05

Run onboarding and test the connection

The first-run setup flow saves your destination and runs a real test upload. It verifies SSH auth, host-key trust, remote directory creation, writability, upload, and cleanup.

06

Customize clipboard output

By default filefling copies the raw remote path, but you can use a template for AI prompts, Markdown, or any text you paste often.

Please inspect this screenshot: {{remotePath}}
07

Send something

Use the menubar button, preview the latest screenshot, drag a file into the window, or press the global hotkey.

⌘⇧F
08

Paste into your terminal

After a successful upload, the rendered clipboard output is ready to paste into your shell, editor, chat, or AI session.

Please inspect this screenshot: /home/brad/shared/2026-06-26_203015.png

Configuration

Destination profiles

filefling can store multiple named destinations. Each destination keeps its own SSH connection fields, remote path, SSH config alias, and clipboard template. When more than one destination exists, the main window shows a destination picker above the drop zone.

new

Create destinations

In Settings, create a destination copied from the current connection, rename it, then adjust host, path, key, and clipboard output.

pick

Switch before sending

The active destination is used for hotkey sends, drag-and-drop uploads, test uploads, and history retry/send-again actions.

Configuration

Clipboard templates

The default template copies the raw remote path. You can replace it with an AI-agent prompt, Markdown image syntax, or any multiline text you paste often. Unknown placeholders are left visible so mistakes are easy to spot. 

{{remotePath}}

Please inspect this uploaded file: {{remotePath}}

![{{filename}}]({{remotePath}})
{{remotePath}}The full path to the uploaded file on the remote machine
{{filename}}The uploaded filename
{{host}}The active destination host
{{username}}The SSH username
{{timestamp}}The upload timestamp as an ISO string

Daily use

Ways to send

⌘⇧F

Latest screenshot

Press the hotkey or click “Send.” filefling uploads the newest image in your screenshot folder. The main window shows a thumbnail, filename, time, and size before sending.

drop

Any file

Open the menubar window and drag a file onto the drop zone. filefling preserves the filename, with unsafe characters cleaned up.

again

History actions

Search recent sends, copy rendered output, copy the raw path, retry failures, send a local file again, reveal it in Finder, or delete one item.

SSH

SSH config support

filefling can read concrete hosts from ~/.ssh/config and simple Include files. It imports HostName, User, Port, and the first IdentityFile into the destination fields. 

Host devbox
  HostName 100.64.1.2
  User brad
  Port 22
  IdentityFile ~/.ssh/id_ed25519

Advanced OpenSSH options such as ProxyJump, ProxyCommand, Match, and agent forwarding are not applied yet. Wildcard hosts are ignored in the picker.

Security

Host-key trust

filefling uses trust-on-first-use host-key verification. It stores host, port, algorithm, SHA256 fingerprint, and trust time. If a server key changes, filefling shows a mismatch warning with the old and new fingerprints. Trusted keys can be reviewed and forgotten in Settings. For background, see the OpenSSH known_hosts format.

Help

Troubleshooting

No screenshots found

Check the Screenshot Directory setting. It needs to point at the folder where macOS saves screenshots. Use the Refresh action in the preview area after changing it.

Permission denied / auth failed

Confirm the username, host, and SSH key path. Also make sure the public key is installed in authorized_keys on the server.

SSH key missing or unreadable

Check the private key path. It should point to a key file such as ~/.ssh/id_ed25519, not a directory. Also check local file permissions.

Host key changed

filefling is protecting you from a possible server identity change. Verify the server, then use Settings → Trusted Host Keys → Forget if you intentionally rebuilt or replaced the server.

Remote path not writable

Create the folder on the server or choose a path your SSH user can write to. The connection test checks this directly.

SSH config host is missing

Only concrete Host aliases are shown. Wildcard patterns such as Host *.internal are ignored because they are patterns, not destinations.

History retry is unavailable

Older history entries may not have local file metadata. Retry, Send again, and Reveal require the original local path to be stored.