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 hereThen 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_hostsCheck 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).
| Key | Default | What it does |
|---|---|---|
host | — | The server. Required. No port here — use port. |
port | 22 | |
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. |
agent | true | Use $SSH_AUTH_SOCK. Set false to ignore any agent. |
known-hosts | ~/.ssh/known_hosts | Where the server’s key is verified against. |
root | login directory | The remote directory the mount maps to. |
connect-timeout | "30s" | Bounds connecting, not transferring. A slow upload is not a failure. |
concurrent-requests | library default | Read/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_ed25519An /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 modeWithout 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 editknown_hosts.key … is passphrase-protected— load it into an agent (ssh-add).no authentication configured— setkey, or start an agent.- remote changes never arrive —
sweep-intervalis 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.