obsidian-cloud-sync syncs a vault to WebDAV or GitHub, and only those two work today

Two back ends work, the rest are placeholders

The development status section is the first thing in the README, and it sets expectations. The project is still at Alpha, and the advice is to back up your notes before syncing important ones.

The sync links are listed explicitly. There are two real, usable paths today. The first is WebDAV, which is implemented and usable for actual syncing, works with services such as Nutstore and Nextcloud, and supports a sync path, a custom directory, automatic sync and manual sync. The second is GitHub, described as an implemented MVP that is usable for real syncing, supporting both public and private repositories.

Everything else is explicitly not there. iCloud is under development and currently has only the interface and placeholder logic, so it is not usable. Google Drive and OneDrive are described as planned, with no backend sync capability implemented at all. The README's own question and answer section repeats this: the two providers that can actually be used are WebDAV and GitHub, and the other providers have not finished their backend implementation.

That is a narrow scope, and it is worth knowing before you install anything. A plugin that shows a provider in its settings screen can suggest a capability that is not there, and here the README is explicit that the interface exists for some providers while the backend does not.

The feature set is about control rather than cleverness

The core feature list is a set of switches rather than a set of clever algorithms, and each one answers a question a vault owner actually has to answer.

On direction, it supports bidirectional sync, upload only and download only. On timing, it supports automatic sync, scheduled sync and manual sync. File creation, modification and deletion are all synced, and there is a basic conflict handling policy.

Two features are worth calling out because they are the ones that separate this from a naive file copy. The first is Markdown link conversion, which handles links when notes move between a local vault and a remote store. The second is selective sync, where you can ignore files, folders and extensions, which is how you keep large attachments out of a Git repository.

Content encryption is optional rather than mandatory, which is a design choice with consequences. It means the plugin can be used as a plain sync tool, and it also means the encrypted and unencrypted cases are separate paths that you should test before you rely on either.

The dependency list supports this reading of the design. The runtime dependencies are crypto-js for the encryption, webdav for the WebDAV client, and monkey-around, which is the patching helper used by Obsidian plugins to wrap methods. There is no cloud storage SDK, no Google API client and no OneDrive library, which is consistent with the claim that only two back ends are implemented.

Installing means building from source and copying three files

The installation section states that only source installation is currently supported. The build is three commands:

git clone https://github.com/ai-bytedance/obsidian-cloud-sync.git
cd obsidian-cloud-sync
npm install
npm run build

After the build you copy the plugin directory into your vault:

.obsidian/plugins/cloud-sync/

And the three files that need to be copied are main.js, manifest.json and styles.css. That is the whole installation, and the reason it is manual is that the plugin is not published to the Obsidian plugin marketplace. The README has a question about that, and the answer is that the project is still at Alpha and both features and stability are still being worked on.

The build itself is a small esbuild setup. The package.json scripts show a dev script that runs node esbuild.config.mjs, and a build script that runs tsc with noEmit and skipLibCheck and then runs esbuild.config.mjs with the production argument. The build command performs a TypeScript check before it bundles, which is why the project lists typescript 4.9.5 and the obsidian package as dev dependencies, and the esbuild configuration lives in esbuild.config.mjs at the repository root. The build output is main.js, which is the file the package.json names as the entry point, alongside the manifest.json that Obsidian reads to identify the plugin.

GitHub sync has quirks you have to design around

The GitHub configuration section recommends a fine-grained personal access token, and the README suggests a minimum permission set: Contents at read and write, and Metadata at read-only. The repository field is filled in as owner/repo, and the README recommends that form, for example ai-bytedance/obsidian-test. There is also a compatibility field for a username, needed only if you put just the repo name in the repository field, and the README says plainly that the owner/repo form is now preferred and the username fallback should not be relied on. The branch is usually main, and the sync path can be left empty or set to something like notes to sync into a subdirectory.

The known limitations section is the part to read before you commit. GitHub does not support empty directories, so a folder you create with no files in it will not appear on the remote, and a directory only shows up once it contains actual files, expressed through the paths of those files. File times on GitHub are approximate, and in extreme cases that can affect a boundary sync decision.

The supported operation list gives a sense of what the back end does: test the connection, recursively list remote files, upload new files, update existing files, delete remote files, and plug into the existing manual and automatic sync path.

The troubleshooting list for a failed GitHub sync is a useful checklist, and it is short: check the token is valid, check the token has Contents read and write, check the repository format is owner/repo, check the branch exists, and check the repository is accessible with the current token.

WebDAV needs a protocol header and has rate limits

The WebDAV configuration asks for four things: the server address, the username, the password, and an optional sync path. The notes on that section are the practical part.

The server address must include the protocol header such as https://, and some services are sensitive to the path format, which is why the README suggests using the test connection to confirm the settings before you sync anything. The most common failure mode for a WebDAV client is not a wrong password, it is a wrong base URL, and the test connection exists to catch that before a first run.

The second warning is about limits. Services such as Nutstore may impose rate limits, so frequent syncing can hit the API quota. That matters for a plugin with automatic sync, since the automatic mode is exactly what generates the request volume that trips a quota. A scheduled sync is the more predictable choice on a rate limited service.

The failure checklist for WebDAV follows the same shape as the GitHub one: check the server address, check the username and password, check the network, check the server side path and permissions, and try the test connection to locate the problem.

The last WebDAV note in the README is about the general shape of the tool rather than a specific provider, and it applies to both: an unstable network raises the failure rate noticeably, and large files with many attachments sync more slowly.

Encryption and GitHub make poor partners for large vaults

The notes section is where the project states its own limits, and the GitHub entry is the most useful warning in the file.

If you use GitHub, the sync essentially becomes writing repository content, which makes it unsuitable as a storage solution for very large files. That is a specific and correct statement, because a git repository stores every revision of every file, so a vault with large attachments grows the repository quickly and every sync writes a new blob.

Encryption has its own risk. Once encryption is enabled, the key must be kept carefully, because losing the key means historical content can no longer be decrypted. There is no recovery path described in the README, so the key is the only copy of the data in a meaningful sense, and treating it as something you can regenerate later is a mistake.

The Markdown link handling has a related caveat. Links are processed for compatibility on upload, so certain special forms may render differently in other editors than they do in Obsidian. The plugin rewrites what it needs to make links portable, and that rewriting is not perfectly reversible across editors.

The difference in approach is that a dedicated sync service is a maintained product with an account and a server on the other end, while this plugin talks directly to storage you already have, which is why it can do WebDAV and GitHub without asking for a subscription and why its provider list is short.

On maintenance, the last push was on 2026-04-20 and the repository is not archived. The releases are 1.0.0 on 2025-05-07, 1.0.1 on 2025-06-13 and 1.0.2 on 2025-07-20, and the licence is MIT with a LICENSE file at the root, which is a permissive grant and a licensing note rather than legal advice. The version in package.json is still 1.0.0, which is a small inconsistency with the published 1.0.2 tag, and the version script suggests the release process updates manifest.json and versions.json rather than the package manifest.

Editorial conclusion

Adopt obsidian-cloud-sync if you need to keep an Obsidian vault on WebDAV or in a GitHub repository and you can live with an Alpha plugin installed from source. Do not adopt it if you need iCloud, Google Drive or OneDrive, since none of those back ends are implemented. Verify first that the plugin is installed correctly by checking the three files in the plugin folder, that you back up the vault before the first sync as the README insists, and that you keep the encryption key safe, because losing it means the history cannot be decrypted.

Frequently asked questions

Official sources

1. ai-bytedance/obsidian-cloud-sync on GitHub
2. Issues
3. License: MIT
4. README
5. Releases