FileFerry — User Guide
Transfer files and open a terminal on the same server. This guide covers everything the app does, in the order you normally need it.
1 — Getting started
FileFerry shows a sidebar with your servers on the left and the working area on the right. As long as no connection is open, the welcome area sits there with the seven protocols.
A new access takes three steps: add a server, add a connection to it, connect.
The difference between a server and a connection is the heart of the app. A server is the machine — address, name, notes. A connection is a way in: a protocol, a user name, a password, a starting directory. One server can have several connections.
Because the same machine often has several doors. Your web host offers FTP for the pages and SSH for maintenance. Your NAS speaks SMB on your own network and SFTP from outside. One server, two or three connections — and each remembers its own directory, its own window size and its own column widths.
2 — Servers and connections
Adding a server
At the bottom of the sidebar you will find Add server. Two entries are needed:
| Field | Meaning |
|---|---|
| Display name | What the server should be called on your side. Anything you like — “Web server” or “NAS basement”. |
| Hostname / IP | The address. Either a name like myserver.com or a
number like 192.168.0.72. |
| Notes | Optional. Room for whatever you want to remember. |
https:// in the address field
Only the name belongs there: myserver.com, not
https://myserver.com. Whether the transfer is encrypted is
decided by the switch in the connection, not by how you spell the
address.
Adding a connection
An expanded server lists its connections and, at the bottom, Add connection. Which fields appear depends on the protocol. These are there for all of them:
| Field | Meaning |
|---|---|
| Protocol | FTP, FTPS, SFTP, WebDAV, SMB, S3 or SSH. |
| Label | Optional. Useful when one server has several connections — “Admin” and “Web space”, say. |
| Port | Set automatically when you change the protocol. Only change it if your provider names a different one. |
| Path on the server | The directory the connection should open in. / is the
root. |
| Method | Password or anonymous. On SFTP the SSH key is offered here as well. |
| User name | Your account on the server. |
| Password | Goes into the macOS Keychain, not into the database. |
| Single click action | Whether a click in the sidebar connects straight away or first shows the details of the connection. |
Groups and order
Groups belong to the sidebar — they do not appear when you add a server. At the bottom you will find Add group; after that you can drag servers into it, and several servers sit together underneath it.
Servers can be put into groups and sorted within them. The button with the two arrows at the bottom of the sidebar turns reordering on; entries can then be dragged. A second click ends it.
A server can also be dragged onto a group header — then it changes group.
3 — The protocols
FTP and FTPS
FTP sends everything in the clear, the password included. On your own network that is defensible; over the internet it is not.
FTPS is the same thing encrypted. FileFerry uses the explicit variant: the connection starts unencrypted on the usual port 21 and then switches over. That is how practically every provider works.
That is normal and FileFerry copes with it. On the first connection it shows the fingerprint and asks. After that it is checked on every session. See Security.
SFTP
SFTP runs over SSH and is therefore fully encrypted. It has nothing to do with FTP apart from the name. The standard port is 22.
There are two ways to sign in:
- Password — as with FTP.
- SSH key — safer and with no typing. Either paste the contents of the private key into the field, or name the file via Choose ….
What is needed is the file without the .pub
extension. The one with .pub belongs on the server, not in
FileFerry.
If the key is protected by a passphrase, FileFerry asks for it when connecting. You can store it with the connection if you want; it then goes into the Keychain.
On SFTP only, FileFerry computes a checksum over the file on the server after the transfer and compares it with the local one. That is the most precise proof there is.
WebDAV
WebDAV runs over HTTP or HTTPS and is offered by Nextcloud, ownCloud and
many hosts. The HTTPS switch decides on encryption;
the path points at the WebDAV directory — on Nextcloud something like
/remote.php/dav/files/YourName/.
SMB
SMB is the protocol of Windows and NAS shares. It has one level more than the others: first the server, then the share, then the directories.
- Leave the path at
/and FileFerry shows the server's shares as folders. - Put
/Publicthere and the connection opens inside that share.
If your account belongs to a domain, write the user name as
DOMAIN\User.
File permissions cannot be set over SMB — the server manages those itself. And you cannot move directly between two shares; download and upload again instead.
S3
S3 is object storage. There are no directories there: an object is called
photos/2026/house.jpg, and that is one name in which
the slashes are ordinary characters. FileFerry shows you a tree anyway and
does the conversion in the background.
An S3 connection needs more entries than the others:
| Field | What goes in |
|---|---|
| Hostname | The provider's endpoint, without https://. On
Cloudflare R2 something like
<account-id>.r2.cloudflarestorage.com. |
| Bucket | The name of your bucket. One connection belongs to exactly one. |
| Region | On Amazon something like eu-central-1, on Cloudflare R2
auto, on MinIO or Garage whatever the server
expects. |
| Bucket in the path | Off for Amazon, on for MinIO and Garage. R2 and Backblaze accept both. |
| User name | The access key. |
| Password | The secret key. |
The connection form has a S3 setup help button with the entries for the common providers.
Large files
Above 5 GB, S3 requires the transfer to go in parts. FileFerry switches over by itself. If the line drops, it remembers which parts arrived and picks up there on the next attempt.
If a multipart transfer is left behind, the parts already sent sit invisibly in the bucket — they appear in no listing and Amazon bills them monthly all the same. FileFerry checks when connecting and asks whether they should go.
What S3 does not have
Renaming folders is not available. S3 has no rename; every object under the folder would have to be copied and deleted one by one. Single files can be renamed.
SSH
A plain SSH connection shows no file lists, only a terminal. See The SSH terminal.
4 — The window
The main window has three areas.
- The sidebar on the left with groups, servers and connections. A click on a connection opens it.
- Your Mac in the middle — the local side.
- The server on the right — the remote side.
Above each list sits a toolbar, below it a row with the search field, and below that the path. Across the top runs the connection header: server name, protocol and port, the Sync directories button, and on the right the session log with the number of lines plus the state.
The dot next to Connected glows green as long as the connection holds. The cross beside it disconnects.
The toolbars
| Icon | Effect |
|---|---|
| Eye | Show or hide hidden files. |
| Folder | Sort folders first, or in among the files. Separate for each side, remembered per connection. |
| Folder with plus | Create a new directory. |
| Trash | Delete what is selected. |
| Arrow | Upload or download. The number beside it says how many entries are selected. |
Navigation
A double click opens a folder. The path above is clickable: every part jumps there. The button with the clock shows the directories you visited recently.
What the window remembers
Every connection reopens its last local and remote directory, along with the window size, the split between the lists and the column widths. Whether that happens separately per connection or jointly for all of them is set under Settings › General.
5 — Transferring files
Select, then press the arrow in the toolbar. Whole folders work just like single files.
What happens along the way
FileFerry does not transfer straight onto the target name.
It uses a side name with the extension .ffpart, and only renames
it once the transfer is complete and the check has passed.
The reason: if the line drops halfway, your existing file on the server is untouched. Without that detour you would have half a file and the old one would be gone.
The check
After an upload FileFerry asks the server for the size and compares it with the local one. On SFTP a checksum is added. If anything does not match, the target file stays as it was and the side file is cleared away.
Because a “226 Transfer complete” is what the server says, not the state of the file. A full disk, an exceeded quota or an aborted write can all produce the same answer.
When the name is already taken
Then FileFerry asks: Replace, Skip or Stop. With Apply to all the answer holds for the rest of the transfer.
File permissions
On FTP, FTPS, SFTP and SSH you can set permissions: right click, Set permissions …. Either with checkboxes or by typing the octal value. Several entries at once work too.
If the server refuses individual files — usually because they belong to another account — a list follows afterwards with the reason for each. The rest are set.
Refresh automatically
The button with the circles in the remote toolbar makes FileFerry re-read the directory at intervals. Useful while something is being produced on the server.
6 — Searching and sorting
Searching
Below each toolbar sits a search field. It searches the directory on screen, not the subfolders.
You write it as in the shell: * stands for any number of
characters, ? for exactly one.
| Entry | Finds |
|---|---|
*.jpg | all JPEG files |
*ndex*html | index.html,
Index-old.html |
holiday | anything with “holiday” in the name |
image?.png | image1.png, but not
image12.png |
A pattern without wildcards searches within the name. As
soon as a * or ? appears, the pattern is taken
literally. Upper and lower case make no difference.
Return runs the search. The matches are selected — the list stays complete, nothing is hidden. The selection is therefore exactly what the arrow transfers. The cross in the field clears it and drops the selection again.
Sorting
A click on a column header sorts by it, a second click reverses the direction. The choice is kept per connection.
The folder icon in the toolbar decides whether folders sit at the top or are sorted in among the files — the latter is what Finder does. Both sides can be set independently.
7 — Folder sync
The Sync directories button in the header opens an area at the bottom of the window that compares the local directory on screen with the remote one on screen.
The area keeps the pair it was opened with. You can carry on navigating in the lists above without the comparison sliding away. For the pair currently on screen there is Compare again.
The preview list
Every row names both sizes, both timestamps and a proposal. Only what is ticked is transferred. The bottom says how many files that is right now; Start sync carries it out.
Transfer all ticks everything that can be transferred, None clears the selection. If there are deletion rows, they get their own bulk button in red — a single “all” would throw transferring and deleting together into one click.
Whatever matches does not appear at all. Where there is nothing to do, no row belongs.
| Proposal | Meaning |
|---|---|
| Local newer | Ticked. The file will be transferred. |
| Size differs | Ticked when no usable comparison of timestamps was possible. |
| Server newer | Shown, but not ticked — otherwise an older version would overwrite a newer one. |
| Local only | Can be ticked once Create new files is switched on. |
| On the server only | Can be ticked once Delete surplus is switched on. Shown in red. |
The switches
- Direction — to the server or to local. The two switches below turn with it.
- Include subfolders — compares the whole tree instead of only the top level.
- Create new files — off by default.
- Delete surplus — off by default, and a confirmation with the count comes before it runs.
Locally too — not into the Trash. A delete that ends up in the bin on one disk and is irrecoverable on another would be worse than one that always means the same thing.
Exclusions
The Exclusions … button opens a window of its own. Whatever matches a pattern does not appear in the comparison at all — and is therefore neither transferred nor deleted.
- A pattern without a slash checks the name at any depth:
*.jsoncatches subfolders too. - A pattern with a slash checks the path from the folder
the sync started in:
images/raw/*.
The quicker way is through the comparison list: right click a row and exclude by name, extension or path. The pattern lands in the open list; saving is what stores it and runs the comparison again.
Exclusions apply per connection, not per pair of folders.
What the sync remembers
After every run FileFerry records, per pair of folders, which files are in sync. Next time the rule is: if nothing changed locally and the size on the server is the same, both sides match — regardless of what the timestamps say.
This is necessary because timestamps are unreliable across the protocols. Some servers only deliver minutes, some no time zone, and after an upload the file carries the server's clock.
While a sync is running
Looking and navigating stay available. What is locked are the context menus, creating folders, deleting and the transfer buttons — they would get in the way of the run.
8 — The SSH terminal
On an SSH connection, and on SFTP via the tab at the top, FileFerry opens a full terminal on the same server.
Several terminals
The plus on the right of the tab bar opens another terminal on the same login. No second session is created on the server. The cross on a tab closes that terminal; the dot in front of it shows whether it is connected.
How many there may be at most is set under Settings › Connections.
Snippets
Commands you keep typing can be stored under Settings › Snippets and sorted into categories. A button in the terminal brings them up. For each snippet you can choose whether it is only inserted or run straight away.
Colour scheme
The palette button in the terminal header changes how it looks: the text and background colours of the terminal. The choice applies to this connection and is kept.
That is more than taste. Anyone with production and a test system open side by side can tell from the colour which window they are typing in.
Settings per connection
| Field | Meaning |
|---|---|
| Terminal type | What the server should be told about the terminal.
xterm-256color is almost always right. |
| Character set | UTF-8, unless the server works without it. Then Latin-1. |
| Command after login | Optional, tmux for instance. |
| Colour scheme | Can also be changed in the terminal itself via the palette — see above. |
Then the terminal type negotiates no window size. FileFerry points this
out and suggests xterm-256color.
9 — Editing files
A double click on a text file on the server opens it in the built-in editor. Saving writes it straight back.
Via Open with it goes to any app on your Mac instead. When you save there, FileFerry writes the file back as well. Which app you chose for an extension is remembered.
10 — Security
Fingerprints
On first contact with a server FileFerry shows the SHA-256 fingerprint of its host key or certificate and asks. After that it is checked on every session.
If it changes, the connection is refused. There is no “connect anyway” button — that is deliberate. A changed fingerprint means either that the server was rebuilt, or that someone is sitting in between. Both deserve checking, not clicking away.
If you rebuilt the server yourself, remove the entry under Settings › Security. You will be asked again on the next connection.
A certificate can be verified on the server:
openssl x509 -noout -fingerprint -sha256 -in certificate.pemWhere the credentials live
Passwords, passphrases and confirmed fingerprints live in the macOS Keychain. Delete a connection and they go with it. The app's own database holds only the name, address, port and path.
App password
Under Settings › Password you can protect FileFerry with a password of its own. The stored credentials are then encrypted on top — without the password they cannot be read outside the app either.
If you want, the app locks itself after an adjustable time without use. If a transfer is running, the lock waits until it has finished.
If you forget the app password, the protection can be reset with the login password of your Mac. The stored credentials are lost in the process — the connections remain, the passwords have to be entered again.
What FileFerry does not do
- No account, no registration, no licence server.
- No usage statistics, no crash reports.
- Sandboxed with no exceptions. Nothing listens on a port.
11 — When something goes wrong
The recovery list
Every transfer is attempted up to three times. Whatever still did not get through lands on a list under Settings › Unfinished — and that list survives quitting the app.
Each entry names the server, the connection and the path. You can retry or discard. Nothing is deleted on the server in the process.
If the local file changed since the failure, FileFerry stops and says so instead of sending a different version. If the new one is the right one, delete the entry and transfer the file again.
The session log
The Log button in the header shows every line of the
running session exactly as it goes over the wire — on FTP that means
220, USER, 331, PASV and
the rest.
Every line starts with the time to the millisecond, then the direction marker:
| Marker | Meaning |
|---|---|
> | FileFerry sent this. |
< | The server answered this. |
* | A note from FileFerry itself, such as opening the data connection. |
When a server behaves oddly, its exact words are here. The Update automatically switch keeps the view running. Beside it one button copies everything, a second clears the view.
The log file
Under Settings › Log file you can switch on a lasting file. It holds connections, transfers and errors across sessions.
The view can be filtered by level — debug, info, warning, error, each switched on and off on its own. The copy button copies what you see; filter for errors and you get exactly those.
It contains server names, user names and file names. Not passwords. Look into it anyway before you send it.
When no connection comes about
Before every connection FileFerry knocks briefly and waits no more than three seconds. That establishes the real reason, instead of a guessed message after twenty seconds.
| Message | Meaning |
|---|---|
| Does not answer | Machine off, asleep, or not on the network. |
| Reachable, but no service | The machine is running, but nothing on this port. Wrong port, or the service is not running. |
If nothing answers the first knock, FileFerry tries again a second later. That helps with servers on Wi-Fi with power saving enabled, which only wake up on the first packet. The log records when the second attempt was needed.
12 — Backup
Under Settings › Backup you can write servers, connections and credentials into a file.
The folder has to be chosen once — macOS only grants an app access to folders that were named in the open dialogue.
The Protect backup with a password switch encrypts the credentials. Without it, passwords and keys sit readable in the file.
Restoring adds and updates, it never deletes. Existing servers and connections are brought to the state of the backup, missing ones are created. Open sessions of the affected connections are disconnected.
The most recent backups are kept; the oldest drop out automatically.
13 — Settings
| Tab | Contents |
|---|---|
| General | Confirmations before deleting, restoring the last directories, window size and layout per connection. |
| Connections | How many sessions stay open at once, how many terminals per connection. |
| Appearance | Light, dark or follow the system. Thirteen accent colours. |
| Language | Thirteen languages, switching without a restart. |
| Shortcuts | Assign keyboard shortcuts yourself. |
| Snippets | Commands for the terminal, sorted into categories. |
| Security | Known host keys and certificates. |
| Password | App password and locking on idle. |
| Unfinished | Transfers waiting to be retried. |
| Backup | Backing up and restoring. |
| Log file | Switch the log file on and off, choose the level, look at it. |
| Info | Version, open-source components used, what's new. |
Keyboard shortcuts
Every action can be given a shortcut of its own. Click the field, press the keys. At least one of Command, Option or Control has to be among them. Escape cancels.
If a combination does not react, it is taken system-wide by macOS or another app. Then only a different one helps.
14 — Common questions
The connection fails although the credentials are right.
Look into the session log. The server's exact answer is there. For FTPS over port 21 the explicit variant has to be chosen — that is FTPS, not the HTTPS switch.
An upload fails with “Forbidden filename”.
Some servers allow no files at all in the topmost directory — on QNAP devices only the shares live there. One level down it works.
The sync keeps proposing the same files.
Then the server delivers no usable timestamps. After the first run FileFerry records the state, and it should settle from then on. If it does not, the checksum on SFTP takes over, which happens automatically anyway.
A local folder cannot be opened.
macOS only releases folders to an app that were named in the open dialogue. Use Choose folder in the local toolbar. FileFerry remembers the permission across restarts.
There is a file ending in .ffpart on the server.
That is the remains of an aborted transfer. FileFerry clears such remains away itself; if one is left behind, you can delete it safely.
How do I get the “What's New” window back?
Under Settings › Info.