Finder & Files

Turning it on

Open a bookmark and enable its “Show in Finder” (Mac) / “Show in Files” (iPad) section. The server appears as a location in the sidebar; you can point it at a specific remote folder, or leave it on the login home directory. Edit a remote file in your favorite editor, save, and the change goes straight back over SFTP.

• Auth must work headlessly: the bookmark needs a stored key, a stored password, or built-in-agent keys, because Finder wakes the integration in the background where interactive prompts can’t appear. Key-Agent Relay bookmarks are excluded for the same reason — no surprise 1Password prompts from Finder.
• Trust is established in the app first: the host must be SSHFP-verified or already pinned via a normal connection. The integration never shows trust prompts of its own.
• On the Mac, new locations may need enabling once under System Settings → Login Items & Extensions → File Providers.

Keeping the view in sync

The system caches file listings so browsing feels instant — which means the view can lag behind changes made server-side. uSSH puts the remedy under your finger instead of guessing, with three tiers per bookmark:

• Resync Now — makes Finder or Files re-check every file against the server. Use it whenever a listing looks stale. It doesn’t re-download unchanged files.
• Remove Downloaded Copies — turns downloaded content back into placeholders that re-download on next open; the way to force fresh contents, or to reclaim space.
• Reset Sync State… — removes and re-adds the location for a guaranteed clean slate. Unsynced local changes in that location are lost; files on the server are never touched.

There is also a global lever: Settings → General → Pause Finder integration. Turning it on unregisters every uSSH location and stops the extension; turning it off again re-adds them all from scratch. Toggling it on and off is the quickest way to force a full, clean resync of every location at once — the equivalent of Reset Sync State for all bookmarks in one go, with the same caveat that unsynced local changes are discarded.

With live updates on (next section) none of this is usually needed: changes on the server show up by themselves.

One iOS quirk worth knowing: after the location is first set up, or after Reset Sync State, the Files app may show Syncing with uSSH Paused and a badge on the location for a while. Nothing is wrong — iOS runs a one-time maintenance pass over a new location only when the device has been idle for a few minutes, and Files reports “paused” until then. Browsing works throughout, and the footer switches to Synced with uSSH on its own. The same menu also offers Reload Domain, a restart of the location without data loss.

Live updates from the host

Manual resync is the fallback; the normal path is for the location to keep itself current. Turn on Settings → General → Live updates from hosts, then Live updates from the host on a bookmark, and uSSH installs a small helper, ussh-fsmonitor, into that account’s ~/.local/share/ussh/ on the server. It watches the location with the operating system’s own change notifications (FSEvents on macOS, inotify on Linux) and streams changes to uSSH, which hands them to Finder or Files as they happen — a file saved on the server appears in an open Finder window within a fraction of a second.

• It runs as your SSH user and never elevates on its own, over the same SSH connection, and only while uSSH or the Finder/Files integration is actively using the location. A root@ connection gets no helper unless you opt in for that bookmark — which lets it run as root and is flagged with a clear warning, since it removes that safeguard. It writes nothing on the server but its own output; delete the folder to uninstall.
• It is verified before it is ever uploaded. Each helper ships with a signed statement; uSSH checks the signature against the release key published in DNS — validated by its own DNSSEC resolver, the same way it verifies your hosts — and the binary’s digest against the statement. The helper’s source is public.
• It authenticates headlessly with the credential copy stored for Finder, so it never asks for Touch ID on its own; a bookmark without a copy simply gets no feed.
• Very large trees can exceed a Linux host’s inotify watch limit; the bookmark then shows a note that live updates cover part of the location, and Resync Now still matters for the rest.
• Optionally, uSSH can fetch newer helpers from ussh.au between app updates, under the same signature and digest checks — off by default.
• It watches only what you are looking at. Since helper 0.3.0 the feed covers the folders currently open in Finder or Files (plus the location’s top level), each on its own and none of their subfolders, and restarts itself as folders are opened and closed. A busy home directory no longer streams every change under it; uSSH upgrades the helper on your hosts automatically.
• On iPad and iPhone, live updates need uSSH open. The feed is an SSH connection held by the app, and iOS suspends a backgrounded app within seconds; the Files extension keeps a feed of its own only for as long as the system keeps it alive. Whenever uSSH comes back, every open folder is re-checked in full, so anything created or removed in the meantime is reconciled at once. Without uSSH running, leave and re-enter a folder to list it fresh. On iPad the easy way to keep it alive is the windowed multitasking mode: give uSSH a window in the same screen group as Files and iPadOS keeps it running instead of suspending it. The window does not have to be visible — Files can cover the whole screen with uSSH entirely behind it; a half swipe up shows it is still there — and the folder stays live for as long as the two share the screen.

How it behaves

• Deletes happen immediately on the server — there is no server-side Trash to fish things out of. uSSH is honest about this rather than pretending otherwise.
• Permissions are respected: what your SSH user can’t write, Finder can’t either.
• A root@ connection mounts read-only by default. Browsing and opening work; creating, editing, renaming, and deleting are turned off, because one stray drag as root has no undo. Each bookmark has a Mount read-only switch, so you can grant write access to a root host you administer — or lock any bookmark read-only regardless of user.
• Uploads are written to a temporary name and moved into place, so a half-transferred file never masquerades as the real one.
• Symbolic links are followed on the server. A link to a folder outside the location — /opt, another user’s tree — opens in place like any folder, because the server resolves the path. Deleting a link removes the link, never what it points to.
• Locations work even when uSSH isn’t running — the extension keeps its own copies of the credentials it needs, listed under Copied for Finder & Files in Settings → Keys.