# filefling documentation

filefling is a macOS menubar utility that sends screenshots and files from a local Mac to a remote AI coding machine over SSH/SFTP, then copies a rendered clipboard output for pasting into a shell, editor, chat, or CLI AI-agent session.

## What filefling is for

filefling is built for users who work with remote AI coding agents, CLI agents, shells, or tmux sessions and need to quickly make a local screenshot or file available on that remote machine.

Typical workflow:

1. Configure one or more SSH destinations.
2. Pick the active destination when needed.
3. Press `⌘⇧F`, click Send, or drag a file into the menubar window.
4. filefling uploads the file over SFTP.
5. filefling copies a raw path, Markdown snippet, or prompt to the clipboard.
6. Paste the output into the remote workflow.

Default copied output:

```text
{{remotePath}}
```

Example rendered output:

```text
/home/brad/shared/2026-06-26_203015.png
```

## Requirements

Before using filefling, you need:

- A Mac running filefling.
- A server or remote machine reachable over SSH.
- An SSH username.
- A private SSH key on your Mac.
- A writable folder on the remote machine.
- Optionally, host aliases in `~/.ssh/config`.

## Getting started

### Beta download

The current public build is a beta Apple silicon ZIP:

```text
https://filefling.netlify.app/downloads/FileFling-1.0.0-beta-arm64.zip
```

It is currently unsigned, so macOS Gatekeeper may ask you to approve the first launch.

### 1. Install filefling

Download the macOS beta ZIP, unzip it, and move filefling into Applications. Launch it from Applications. It appears in the menubar.

### 2. Verify SSH from Terminal

filefling uses your existing SSH access. Confirm that SSH works before configuring the app:

```sh
ssh your-user@your-host
```

### 3. Use SSH config or enter details manually

If your server is already in `~/.ssh/config`, choose that host during setup to fill `HostName`, `User`, `Port`, and `IdentityFile`.

Example SSH config:

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

If you do not use SSH config, enter host, port, username, remote path, and key path manually.

### 4. Choose the remote upload directory

Pick the folder where screenshots and files should land.

Example:

```text
~/shared
```

filefling can create this directory during the connection test if your SSH user has permission.

### 5. Run onboarding and test the connection

The first-run setup flow saves your destination and runs a real test upload.

The test verifies:

- required settings are present
- SSH connection succeeds
- SSH authentication succeeds
- host-key trust is valid
- remote `~/` paths resolve correctly
- remote directory exists or can be created
- remote directory is writable
- a tiny hidden `.filefling-test-...txt` file can be uploaded
- the test file can be removed

### 6. Customize clipboard output

By default, filefling copies the raw remote path:

```text
{{remotePath}}
```

You can use a template such as:

```text
Please inspect this screenshot: {{remotePath}}
```

or:

```markdown
![{{filename}}]({{remotePath}})
```

### 7. Send something

Ways to send:

- Press `⌘⇧F` to send the latest screenshot.
- Open the menubar window and click Send.
- Drag a file onto the drop zone.
- Retry or send again from history when the original local file path is known.

### 8. Paste into your workflow

After a successful upload, the rendered clipboard output is ready to paste.

Example:

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

## Recommended settings

| Setting | Purpose |
| --- | --- |
| Destination | A named profile such as Personal Server, Work Devbox, or VPS. |
| SSH Config Host | Optional alias imported from `~/.ssh/config`. |
| Host | SSH hostname, DNS name, Tailscale name/IP, or server name. |
| Port | SSH port, usually `22`. |
| Username | Remote SSH username. |
| Remote Path | Directory where files should land, e.g. `~/shared`. |
| SSH Key Path | Private key file, e.g. `~/.ssh/id_ed25519`. |
| Screenshot Directory | Local folder where macOS saves screenshots. |
| Clipboard Template | Text rendered and copied after upload. |

## Destination profiles

filefling supports multiple named destinations. Each destination stores:

- host
- port
- username
- remote path
- SSH key path
- SSH config alias
- clipboard template

The active destination is used for:

- hotkey sends
- drag-and-drop uploads
- test uploads
- history retry/send-again actions

When more than one destination exists, the main window shows a destination picker above the drop zone.

In Settings, users can:

- rename the active destination
- create a new destination copied from current settings
- delete a destination, as long as at least one remains
- save connection and clipboard edits back into the active destination

Existing single-destination installs are migrated into a `Default` profile.

## Clipboard templates

Clipboard templates control what text is copied after a successful upload.

Supported tokens:

| Token | Meaning |
| --- | --- |
| `{{remotePath}}` | Full path to the uploaded file on the remote machine. |
| `{{filename}}` | Uploaded filename. |
| `{{host}}` | Active destination host. |
| `{{username}}` | SSH username. |
| `{{timestamp}}` | Upload timestamp as an ISO string. |

Examples:

```text
{{remotePath}}
```

```text
Please inspect this uploaded file: {{remotePath}}
```

```markdown
![{{filename}}]({{remotePath}})
```

Unknown placeholders are left visible so mistakes are easy to spot. Multiline templates are supported.

Send history stores the rendered clipboard text from successful sends, so clicking a history item copies the same output that was copied when the file was originally uploaded.

## Ways to send

### Latest screenshot

Press `⌘⇧F` or click Send. filefling uploads the newest image in the configured screenshot folder.

The main window shows a latest screenshot preview with:

- thumbnail, when macOS can generate one
- filename
- modified time
- file size
- refresh action

### Drag any file

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

### History actions

The Recent list stores the last 10 sends.

Available actions:

- click a successful row to copy rendered clipboard output
- copy raw remote path
- retry failed upload when local path is known
- send a local file again
- reveal local file in Finder
- delete one history item
- clear all history
- search by filename, remote path, local path, or error text

Older history entries may not have local file or file-size metadata, so retry/reveal may not be available for those items.

## SSH config support

filefling can read concrete host aliases from `~/.ssh/config` and simple included config files.

Supported directives:

- `Host`
- `HostName`
- `User`
- `Port`
- first `IdentityFile`
- `Include`, including simple wildcard includes such as `~/.ssh/conf.d/*.conf`

Example:

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

Selecting `devbox` fills the destination fields with host, username, port, and key path.

filefling still performs uploads through its own `ssh2` transport. Advanced OpenSSH options are not applied yet, including:

- `ProxyJump`
- `ProxyCommand`
- `Match`
- agent forwarding

Wildcard hosts such as `Host *.internal` are ignored in the picker because they are patterns, not concrete destinations.

## Host-key trust

filefling uses trust-on-first-use host-key verification.

It stores host-key metadata:

- host
- port
- algorithm
- SHA256 fingerprint
- trust timestamp

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. Forgetting a key causes the next connection to trust the presented key again, so only do this after verifying the server identity.

## Useful links

Stable links for people and agents reading about filefling, SSH-based file sharing, macOS screenshots, AI coding agents, and remote developer workflows.

- [filefling home](https://filefling.app/)
- [Download macOS beta ZIP](https://filefling.netlify.app/downloads/FileFling-1.0.0-beta-arm64.zip)
- [Human-readable docs](https://filefling.app/docs)
- [Guide: send macOS screenshots to AI coding agents](https://filefling.app/guides/send-macos-screenshots-to-ai-coding-agents)
- [Agent-readable Markdown docs](https://filefling.app/docs.md)
- [llms.txt](https://filefling.app/llms.txt)
- [OpenSSH config manual](https://man.openbsd.org/ssh_config)
- [OpenSSH known_hosts file format](https://man.openbsd.org/sshd#SSH_KNOWN_HOSTS_FILE_FORMAT)
- [Apple screenshot shortcuts](https://support.apple.com/en-us/102646)
- [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)

## Troubleshooting

### No screenshots found

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

### Permission denied or auth failed

Confirm the username, host, and SSH key path. 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. If the server was intentionally rebuilt or replaced, use Settings → Trusted Host Keys → Forget.

### 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.

## Security notes

filefling is a local Electron app that reads user-selected files and local screenshot files, then uploads them to a user-configured SSH server.

Security properties:

- SSH/SFTP transport uses `ssh2`; no external `scp` binary is required.
- Host keys are verified with trust-on-first-use storage.
- Host-key metadata includes host, port, algorithm, fingerprint, and trust timestamp.
- Main-process IPC handlers validate renderer input.
- Uploaded filenames are sanitized.
- Remote directories are shell-quoted before `mkdir -p`.
- Local send paths must be files, not directories.
- Clipboard templates are plain string interpolation with a small allowlist of supported tokens.
- SSH config import exposes parsed concrete host aliases only through the preload bridge.