Skip to content
Work in progress — do not trust Drivel with your only copy. It is unfinished, under-tested, and may lose data. Keep backups you have checked. What this means →
SFTP

SFTP

Drivel can sync to any server you have an SSH account on. There is nothing to install at the other end: SFTP is a subsystem of OpenSSH, so if you can ssh to a machine you can already point drivel at it.

What drivel adds over sshfs — which is the honest comparison — is that your filesystem never waits for the network. A write lands in the local backing directory and returns; the upload happens behind it, and retries if the link is down. Add lazy mode and a large remote tree is browsable at full apparent size while holding almost none of it locally. And when two machines edit the same file, you get a conflict copy rather than a silent loss.

Setting it up

The SFTP backend ships inside the drivel binary, so there is nothing to install for it — see Installing if you have a drivel that was built without its backends.

SFTP is configured through the config file . There are no -sftp-* flags; the mount flags are Drive-shaped by history.

[account.server]
provider    = "sftp"
host        = "files.example.com"
user        = "you"
key         = "~/.ssh/id_ed25519"
root        = "/srv/share"

[[mount]]
account        = "server"
path           = "~/share"
data           = "~/.local/share/drivel/mounts/server"
sweep-interval = "5m"          # see "How changes reach you" — the default is wrong here

Then drivel mount.

Before the first mount

The server’s host key must already be in your known_hosts file. Drivel never trusts a key on first use and there is no option to make it — a mount can be brought up by /etc/fstab at boot with nobody watching, so there is nobody to answer a prompt. If you have ever ssh’d to the server from this account you are already done. Otherwise:

ssh-keyscan -H files.example.com >> ~/.ssh/known_hosts

Check the fingerprint against the server before you trust it. Drivel refuses to mount an unknown host and says which file to add it to, so you will not get this wrong silently.

Options

These live in the account table (or [mount.provider], which overrides it).

KeyDefaultWhat it does
host—The server. Required. No port here — use port.
port22
user—The SSH account to log in as. Required.
key""A private key file. Must not be passphrase-protected — see below.
certificate""A signed certificate to present with key.
agenttrueUse $SSH_AUTH_SOCK. Set false to ignore any agent.
known-hosts~/.ssh/known_hostsWhere the server’s key is verified against.
rootlogin directoryThe remote directory the mount maps to.
connect-timeout"30s"Bounds connecting, not transferring. A slow upload is not a failure.
concurrent-requestslibrary defaultRead/write packets in flight per file. Raise it on a long, fat link.

Authentication

Keys, certificates and an agent. There is no password option and no passphrase option, and this is deliberate — either one means a credential sitting in cleartext beside the file it protects, for an account that usually also grants a shell. Use an agent for an encrypted key:

ssh-add ~/.ssh/id_ed25519

An /etc/fstab mount has no agent and no environment, so give it a dedicated unencrypted key with a restricted authorized_keys entry rather than reaching for a password.

How changes reach you

SFTP has no change notification of any kind. There is no feed to subscribe to, so drivel finds out what changed remotely by walking the tree — the same enumeration sweep that reconciles a Drive that existed before you first mounted it, run on a schedule.

That makes sweep-interval the poll interval, and its 24-hour default is tuned for a backend that also has a live feed. It is wrong for SFTP. Set it to what you can tolerate as inbound latency:

sweep-interval = "5m"

A sweep costs one directory listing per directory under your root, and nothing is downloaded to perform one. Minutes are reasonable for a normal tree; seconds are not, on any tree large enough to care about.

Outbound is unaffected — a local change is uploaded within seconds, as always. sweep-interval = 0 disables the sweep entirely, which on this backend means disabling inbound sync entirely.

In the default mode, add materialize

Because the sweep is the only way anything arrives here, one more setting is effectively required on this backend:

materialize = true     # or -materialize, or use lazy mode

Without it a file that exists on the server and not on your machine is listed and left alone, and the sweep says so every time:

[sweep] reconcile complete in 5ms: 4 remote object(s) listed, 3 reconciled locally,
0 pushed, 1 not fetched (add -materialize to download them)

On a backend with a live feed that setting only governs the content that was already there when you first mounted — anything created afterwards arrives through the feed regardless. SFTP has no feed, so it governs everything inbound, forever: without it a colleague’s upload will not appear today and will not appear next week. A mount in that state is upload-only, and the sweep summary is the one place that says so.

Lazy mode does not need it — a placeholder is metadata, so a lazy mount makes the whole server tree visible for the price of a sweep and downloads a file when you read it.

Deletion has no undo here

On Google Drive a removal goes to the trash, so a deletion drivel got wrong is recoverable for 30 days. A server reached over SFTP has no trash, and drivel does not invent one — a hidden directory of deleted files would sit inside the tree being synced, where the next sweep would enumerate it and pull every deleted file back down.

The same goes for conflict copies: conflicts = "remote-trash" is refused on an SFTP mount, because there is nowhere to put them. The default, a .drivel-conflicts folder, works here, as do the local trash and the folder kept on one side; see where the loser goes .

So rm is rm. That matters most for the deletions you did not type: a sweep can infer one, from a wrong premise like a mount pointed at the wrong root or a backing directory that was emptied. The guard is -max-deletes , which abandons a whole reconcile pass rather than trimming it when the count looks wrong — and on this backend it is not the guard in front of a safety net, it is the only guard. Its default of 100 is a reasonable place to start; lower it if your tree is small.

Keep a real backup of anything that matters, as always. See data safety .

What it costs, and one thing to know

Editing part of a large file uploads only that part. SFTP writes at an offset, so changing one block of a 4 GB file transfers one block. Drive cannot do this at all — it replaces the whole object — which makes this the backend where that optimisation actually runs.

A file that is rewritten with identical content is uploaded again. Drivel skips a redundant upload by comparing a server-computed checksum, and no SFTP server offers one by default. The upload is correct, just wasted. Editing part of a large file is unaffected — that takes the offset path above, not this one.

A remote edit can be missed in one narrow case. With no checksum available, drivel identifies a remote file by its modification time and size — the same heuristic rsync uses without --checksum. An upload carries the file’s own modification time, and SFTP keeps it in whole seconds, so an edit that keeps a file’s byte length exactly and was made in the same second as the version drivel last synced is indistinguishable from it, and is not pulled until something else touches the file. It takes deliberate effort to hit; it is listed because it is real.

An edit that reaches the server while drivel is uploading the same file is kept. Just before moving its finished upload into place, drivel checks the file once more; if it changed, nothing is replaced, the other edit becomes a conflict copy, and drivel uploads again. Only the instant between that check and the move is left uncovered.

A renamed folder is downloaded again by your other machines. Drivel finds remote changes here by listing the tree, and a listing cannot tell a rename from a new folder plus a deleted one — whether the rename was made through another drivel mount or directly on the server. So each other machine’s next sweep downloads the folder in full under its new name and deletes the old copy. Those deletions count against -max-deletes like any other a sweep infers, so a folder holding more files than the limit has the whole delete pass refused and stays doubled until you repair it . A machine that made the rename through its own mount is unaffected. On Google Drive a rename is reported as one, so this mostly does not arise there.

Symbolic links, sockets, devices and named pipes are skipped, in both directions, and drivel says how many it stepped over at the end of a sweep. There is no honest way to carry them through a byte-stream interface, and following a link during a sweep would let a loop run forever.

Permissions are not synced. A file drivel uploads gets whatever mode your SSH account’s umask gives it. Ownership, ACLs and extended attributes do not travel. Modification times do, except after an edit drivel sends as just the changed blocks of a large file, which leaves the server’s copy dated to the upload.

An interrupted upload can leave a .drivel-upload.* file on the server. Drivel uploads to a temporary name and renames it into place, so the real path never holds a half-written file. If the mount is killed outright — kill -9, an out-of-memory kill, a power cut — the temporary stays. Drivel ignores these completely: it will not download one, and it will not mistake one for a file you deleted. A sweep removes one that nothing has written to for 24 hours — an upload still in progress keeps its timestamp moving, so only an abandoned one gets that old — and logs [sftp] enumerate: removed N abandoned upload temporary(ies). Before 17 October 2026 nothing removed them; anything matching .drivel-upload.* under your root is safe to delete by hand once no mount is uploading.

When something is wrong

drivel mount -debug logs every operation. The common failures:

  • no host key for … in ~/.ssh/known_hosts — see before the first mount .
  • HOST KEY MISMATCH — the server offers a key that is not the one you recorded. Either it was rebuilt, or something is intercepting the connection. Drivel refuses to connect. Confirm the new fingerprint out of band before you edit known_hosts.
  • key … is passphrase-protected — load it into an agent (ssh-add).
  • no authentication configured — set key, or start an agent.
  • remote changes never arrive — sweep-interval is still at its 24-hour default. See above .

A dropped connection is not an error you need to act on: the operation is retried and reconnects by itself.

Platforms

The SFTP backend is pure Go and builds everywhere Drivel does. What limits where you can mount is unchanged — see platforms .

It is tested against OpenSSH — the sshd almost everything runs. Other servers speak the same protocol and should work; they have not been run.