Filen Sync

by Erik Vaněk
5
4
3
2
1
Score: 51/100

Description

Obsidian plugin for using Filen as cloud save

Reviews

No reviews yet.

Stats

0
stars
692
downloads
0
forks
92
days
8
days
8
days
1
total PRs
0
open PRs
0
closed PRs
1
merged PRs
0
total issues
0
open issues
0
closed issues
33
commits

Latest Version

8 days ago

Changelog

Back up your vault before using this. After installing, log in and press Check connection first, which uploads, downloads, compares and deletes a small test file.

Install

Install with BRAT using NeDDy3z/filen-obsidian, or download main.js and manifest.json below into <your vault>/.obsidian/plugins/filen-sync/ and restart Obsidian.

Verifying this build

main.js was built by GitHub Actions from this repository and signed, so you can check it yourself:

gh attestation verify main.js -R NeDDy3z/filen-obsidian

Licensing

The plugin source is Apache-2.0, but this build bundles @filen/sdk, which is AGPL-3.0. See the README.

Commits: https://github.com/NeDDy3z/filen-obsidian/commits/0.1.8

README file from

Github

Filen Sync for Obsidian

Sync your vault with Filen end-to-end encrypted cloud storage, on desktop and mobile. Talks to Filen directly through the official SDK, so there is no server to run and nothing to configure outside Obsidian.

Back up your vault before using this. It is early software that has not yet been run against a real Filen account, and a sync plugin writes and deletes files on both sides by design. Deletions go to a trash you can recover from and conflicts keep both copies, but neither is a substitute for a copy of your notes somewhere this plugin cannot reach.

Install

Not in the community plugin list yet, so pick one of these until it is.

With BRAT, which also keeps it updated:

  1. Install BRAT from Settings, Community plugins, Browse.
  2. In BRAT's settings, press Add Beta plugin and enter NeDDy3z/filen-obsidian.
  3. Enable Filen Sync under Settings, Community plugins.

By hand, if you would rather not add another plugin:

  1. Download main.js and manifest.json from the latest release.
  2. Put both into <your vault>/.obsidian/plugins/filen-sync/, creating the folder if needed.
  3. Restart Obsidian, then enable Filen Sync under Settings, Community plugins.

Once it is in the community list, Settings, Community plugins, Browse, search for Filen will replace both of these.

Setup

  1. Set Folder on Filen if you want something other than Obsidian/<vault name>. It is created if it does not exist.
  2. Enter your Filen email, password and two-factor code, then press Log in. Only the derived account keys are stored, in this device's keychain through Obsidian's secret storage, never the password. Pasted values are tidied up, so a trailing newline from a password manager or the space in 123 456 from an authenticator app does not break the login.
  3. Press Check connection. It uploads, downloads, compares and deletes a small test file, so a pass means the whole round trip works against your account.
  4. Pick a direction and an auto-sync trigger.
  5. Sync from the ribbon icon, the status bar item, or the Sync now command.

On a second device, install, log in, and point it at the same folder on Filen.

Direction

Mode Effect
Both ways (default) Changes travel in both directions
Vault to Filen only Your vault is the source of truth
Filen to vault only Filen is the source of truth
Off, do not sync Nothing runs, including the automatic triggers

One-way modes do not simply ignore the other side. If the non-authoritative side deleted a file, it is put back from the authoritative one, because ignoring it would leave the two sides permanently disagreeing and re-deciding the same thing on every sync. So in "Vault to Filen", deleting a note on another device brings it back from this vault; in "Filen to vault", deleting a note here brings it back from Filen.

Conflicts follow the direction too. Pushing uploads your copy, and Filen's version history keeps the old one. Pulling saves your copy beside the note as note.conflict-20260818-143005.md before writing Filen's version, so nothing is lost either way.

Auto-sync

Three independent triggers, configurable in settings:

  • After you stop typing. Waits for the vault to be quiet for N seconds. Runs once after a writing session, not once per keystroke. Edits made while a sync is already running are not lost, another sync follows it. The plugin's own downloads do not count as edits.
  • On an interval. Every N minutes.
  • On startup. One sync shortly after Obsidian opens.

On desktop the status bar shows the current state and clicking it syncs. Mobile has no status bar, so it reports through notices instead.

How it works

Every sync compares three things: your vault now, Filen now, and a snapshot of the last successful sync kept per device. The snapshot is what tells a deletion apart from a new file.

To do that it lists every file in the vault and reads each one's path, size and modification time. A sync plugin cannot decide what to transfer without seeing what is there. Exclusions and the .obsidian setting are applied to that listing afterwards, and file contents are only ever read for files that are actually being uploaded.

At last sync In vault On Filen Result
no yes no upload
no no yes download
no yes yes same: skip. different: conflict
yes yes no deleted on Filen, so delete locally
yes no yes deleted locally, so delete on Filen
yes changed unchanged upload
yes unchanged changed download
yes changed changed conflict

Conflicts keep both copies. The Filen version is saved next to yours as note.conflict-20260818-143005.md and your version is uploaded. Nothing is merged, nothing is silently overwritten.

Renames and moves are applied as moves on the other side, not as a delete plus a fresh transfer. A deleted path and a new one are paired when the new file has the same size and modification time the old one had at the last sync, and only when exactly one file matches. If you rename a note and edit it before the next sync, it falls back to delete plus upload, which loses nothing.

Deletions are recoverable. Local ones go to the vault .trash, remote ones to the Filen trash, and Filen keeps previous versions of overwritten files.

Modification times travel in both directions, which is what stops two devices bouncing the same file back and forth forever.

Force sync reconciles as if this device had never synced. It starts from an empty snapshot, so no delete branch above can fire: nothing is removed on either side, and anything that differs becomes a kept-both-copies conflict. Reach for it when two devices have drifted apart.

Syncing the .obsidian folder

Mode Syncs
Off (default) Notes only
Plugins and themes Plugin code, the enabled-plugin lists, appearance.json, hotkeys.json, themes/, snippets/
Everything except window layout The whole folder, per-plugin settings included

Synced settings only take effect after Obsidian restarts. It reads the enabled-plugin lists and the theme once at startup and holds them in memory, so a downloaded community-plugins.json or appearance.json changes nothing on a running app. The plugin tells you when a sync has written settings files. Reload reasonably promptly: if you change a setting first, Obsidian writes its in-memory copy back over the downloaded one, and the next sync uploads that instead.

workspace.json is never synced in any mode. Obsidian rewrites it every time you move a pane, so syncing it means two devices fighting over window layout forever, and a phone layout is not a desktop layout anyway.

The middle mode exists because plugin code is what you actually want on a new device, while plugins/<id>/data.json is the risky part: a running plugin rewrites its own settings from memory at unpredictable moments, so a downloaded copy can be clobbered or read half-written, and those settings are often device-specific. Pick "Everything" if you want it anyway.

This plugin's own folder is always skipped, so your credentials and this device's snapshot stay on this device.

Development

npm install
npm run dev     # watch build into main.js
npm run build   # typecheck and minified build
npm test        # decision table tests, plain node:test
File What it is
src/sync.ts Decision table, direction narrowing, config filtering, snapshot format. No I/O
src/local.ts The vault side, via Obsidian's adapter
src/filen.ts The Filen side, via the SDK's cloud() calls
src/main.ts Plugin, settings, commands, action executor

Releases are built by GitHub Actions, not locally. Push a tag matching the version in manifest.json and .github/workflows/release.yml builds main.js, signs it with a build provenance attestation, and publishes the release. That lets anyone confirm the shipped bundle came from this source rather than someone's laptop:

gh attestation verify main.js -R NeDDy3z/filen-obsidian

src/filen.ts avoids sdk.fs() deliberately. Those helpers resolve paths through an internal cache only sdk.fs().readdir() fills, and sdk.fs().writeFile() is node-only. One getDirectoryTree() call gives the whole subtree instead, and uploads go through cloud().uploadWebFile().

Caveats

  • The account keys live in Obsidian's secret storage on each device, not in the vault, so they are not in vault backups. They grant full access to your Filen drive. Versions up to 0.1.7 kept them in data.json; they are moved out on the first load after updating.
  • @filen/sdk calls itself a work in progress. The version is pinned exactly.
  • Files are held in memory during transfer, so exclude very large attachments or set Max file size. A file over the limit on either side is skipped on both, never deleted.
  • No file watcher beyond the triggers above, so notes can be up to one interval stale.
  • Requires Obsidian 1.13.0 or later, since the settings use the declarative settings API added in that release.

Contributing

Issues and pull requests are welcome. The plugin is small on purpose, so the bar for adding a setting or a dependency is high: if a few lines of plain code will do, prefer that.

Getting set up:

git clone https://github.com/NeDDy3z/filen-obsidian
cd filen-obsidian
npm install
npm run dev

npm run dev rebuilds main.js on every change. To try it in a real vault, symlink the repo into that vault's plugin folder and reload Obsidian after each build:

ln -s "$(pwd)" "<your vault>/.obsidian/plugins/filen-sync"

Use a scratch vault rather than your real notes. This plugin deletes files on both sides when the decision table says to, and a bug in that table is the kind that eats notes.

Before opening a pull request, run npm run build, which typechecks and produces the bundle. Keep an eye on the size of main.js: most of it is the Filen SDK, and anything that pulls in another large dependency needs a good reason.

A few conventions:

  • Commit subjects read as plain past-tense verbs, for example "Added the sync direction dropdown" or "Removed the redundant snapshot write".
  • Comments explain why, not what. If a comment restates the code, delete it. The ones worth keeping record something you cannot see from the code, like why sdk.fs() is avoided or why workspace.json is never synced.
  • Releases are cut by pushing a tag that matches the version in manifest.json. GitHub Actions builds, signs and publishes it.

Contributions are accepted under the same license as the project.

License

Copyright 2026 Erik Vaněk. Licensed under the Apache License, Version 2.0.

Third-party code

The built main.js bundles @filen/sdk, which is licensed under the GNU Affero General Public License v3.0. AGPL-3.0 is a strong copyleft licence, so a distributed build that includes the SDK is a combined work and has to be offered under AGPL-3.0, whatever licence this repository's own source carries. Apache-2.0 code may be combined into an AGPL-3.0 work, but the result cannot be relicensed back to Apache-2.0.

In practice that means the Apache-2.0 licence above covers the source in src/, while any release artifact that embeds the SDK must be distributed under AGPL-3.0 with its source made available. Resolve this before publishing a release: either license the whole plugin AGPL-3.0 to match, or obtain different terms from Filen.

Other bundled dependencies are MIT (buffer, events, path-browserify, and the SDK's own MIT dependencies), BSD-2-Clause (dotenv, progress-stream), and BSD-3-Clause or GPL-2.0 (node-forge).