Obsidian Sync now has a headless client
help.obsidian.mdOh neat, I had come across the headless client yesterday (and submitted a now-fixed bug report for it after running into some issues).
Before opening HN this morning and seeing this post, I actually wrote a post about how I'm experimentally using headless to publish my blog: https://utf9k.net/blog/obsidian-headless/
Well, that post was my experiment but I'll be looking forward to trying it out going forward.
There are of course many alternatives and I'm sure this workflow may have its pains but for now, it feels like a lot less friction between actually writing and having it published.
I've used plain Git for many years of course but I've also tried other rube goldberg machines such as various Git-inside-Obsidian plugins and so on but there's always just a bunch of "stuff" between writing and putting it online.
Also new: Obsidian joins the CLI gang
I’ve been having a lot of fun recently using AI CLIs with Obsidian. No plugins necessary because it’s just a directory tree of markdown files.
I love that CLIs are getting a second wind.
I've been using iCloud to sync Obsidian, and have consistently run into the problem that iCloud file container access needs full disk permissions that I don't want to give the agent (or Ghostty). Does everybody use Obsidian's paid sync instead or what? Or SyncThing?
Definitely one of the biggest ROI is to pay for the sync. I regret all years I tried git-based alternatives (it's still useful to have it in git for backup, but not as the main syncing mechanism).
I just pay for the sync.
I like that I can have some vaults that sync to both my personal and work laptops and other vaults that only sync to one or the other.
It’s awfully convenient without any vendor lock in since I can just take my plain markdown files and leave anytime.
Just pay for the sync. I used to juggle with git, rsync, inotify etc and other tools
Its one of the few subscriptions where it actually feels like money well spent
I was using SyncThing, and it worked, but any time you have an Obsidian vault open on two devices, or shortly after another, you're always thinking about if you're going to have to clean up a bunch of sync conflict files later. And that mental overhead is not worth saving $4/mo.
The conflicts are never hard: it's like a git merge conflict where you just take the latest of every conflict block.
I used to use SyncThing, then Dropbox, then iCloud. But then I just caved and paid for Obsidian Sync and it is the best money spent aside from Claude. I don't have to tinker with weird settings anymore or deal with sync issues, it just works.
I can't wonder if that's by design to make it hard for a plugin to have it's own sync mechanism. Definitely not proof of this that I know of, but a thought.
Obsidian is plain Markdown and JSON files.
There can't be a will from the devs to make it hard to sync.
It's just that unlike git or Dropbox or whatever, that are just generic "syncing" tools, Obsidian Sync has been built to provide the best experience with Obsidian.
I'm talking more about the plugin architecture not about the file format or third-party applications. sync plugins seems to be pretty limited compared to what's offered for a subscription.
Same
Im just running a Nextcloud on a raspberry pi to sync everything. Works flawlessly for multiple years now.
I use Syncthing (with Synctrain client on iOS) and it works great.
protip: You can make synctrain sync with an iOS shortcut, with the shortcut being triggered when Obsidian is opened or closed. This means you're always in sync, even if iOS hasn't allowed synctrain to run in the background.
I've had good luck with syncthing. But I only sync between laptop and desktop.. the mobile story with syncthing isn't ideal.
I use both and I prefer their builtin sync, since I also code on Linux.
I used iCloud in the past, but found that syncing between a few devices sometimes left my notes in a weird state - sometimes overwritten, missing, etc. I switched some time ago to https://github.com/remotely-save/remotely-save with backblaze and I periodically sync to a git repo for a second backup. No issues since then.
I have been using remotely save and a free bucket from backblaze. It as a s3 compatible api so works using the s3 feature.
I'm doing the same since this is the only method I found I can let my bot access the files, something I couldn't achieve with Obsidian Sync.. until now!
I built a one-time purchase solution that might help you.
- https://isolated.tech/apps/syncmd
- https://isolated.tech/apps/syncmd/blog/obsidian-git-ios-setu...
You can git clone directly to your iOS file system which fixes the Obsidian git plugin issue so you can use the Obsidian git plugin on your computer and mobile devices.
Obsidian's paid sync works great for me.
Resilio.
I did run with this setup for a few months (I believe like, 5 months already?) and when it works, it's nice, but 90% of the time it has been extremely painful.
Something breaks, one automatically updates and then it breaks the entire database, SCRAM mode, recovering is painful, and all the time I get warnings, spam and logs, it's anything but seamless.
Which is a real pity, because when it works it feels magical to use within my laptop, my phone and my tablet, all self hosted, but the pain won and so I'm searching for new alternatives.
I use this and a self-hosted couchdb. So far it seems to be good, but I haven't spent more than a few hours with it yet. I do have what appears to be a working setup on ios, macos, and linux. Obsidian's large number of plugins and control surfaces is a bit hazardous.
github private repo works fine
It's not super useful yet- you can't really view notes in the CLI but you can can trigger features like search.
Notes are stored in Markdown files. Why do you need Obsidian CLI to view notes when `cat` will do?
Okay, so my command line fu is not what it perhaps should be, but if I could use obsidian without the bloated app, I'd be even more in love.
How would I be able to search obsidian links from the command line?
Like, to travel between notes in the app of course I can just click on connecting links or search, but I wouldn't have the faintest idea how to do that in a cli.
Is there some handy way to search the current folder and subfolders for text in a file with regex? Like some kind of >find term for all of my [[term]] entries in markdown files ?
What is obsidian beyond a pile of markdown files without the app?
ripgrep?
Hackernews is accessed using http. Why do you need a web browser when curl exists?
You can view notes with Obsidian CLI. See the "read" commands. But also you can do that with your built-in command line tools.
Oh snap! Thanks for that, I can really make good use of this!
Oh! I worked on this project. If anyone has questions, I'll do my best to answer them!
Wanted to say thanks. We were literally talking about the lack of a cli sync at work last week and I had moved to Syncthing because of that gap.
Definitely will be looking at the official Obsidian sync plan now.
How are sync conflicts handled in the filesystem? Say I write to a file and another client's edit wins and mine is rejected.
The headless Obsidian Sync client works the same way as desktop and mobile clients, see:
https://help.obsidian.md/sync/troubleshoot
- Markdown files: Obsidian Sync merges the changes using Google's diff-match-patch algorithm.
- Other file types: For all other files, including canvases, Obsidian uses a "last modified wins" approach. The most recently modified version replaces earlier versions.
For conflicts in Obsidian settings, such as plugin settings, Obsidian Sync merges the JSON files. It applies keys from the local JSON on top of the remote JSON.
Are there plans to support scoped token permissions (specific folders or even specific notes)? I'd love to try setting up something that automatically updates a specific Obsidian note on a state change or cronjob, but I'd want to avoid giving access to the rest of the vault.
also, thanks for the great product, bought the vip catalyst as a show of support.
Related tangent: "Relay" (https://relay.md") lets you sync / share files based on directory (vs. the whole vault). That enables things like "my private vault contains a subdir for work, and my work machine syncs to only that child subdir".
Thanks for your support! Sync is end-to-end encrypted so the server doesn't know about specific paths in your vault. You would have to set those permissions at the filesystem level, or with the tool you're using.
No question. Just wanted to drop by and say Obsidian is actually pretty cool. An absolute joy to use, and I only wish I learned about it earlier than I did.
It would be nice if one could sync dot files in the vault. For example, the .claude or .pi folder containing skills and whatnot.
Yes, we're looking into that!
No questions, just thanks for helping with a great product.
This was my most-wanted Obsidian feature, so I’m thrilled to see this. It’s going to be great for server-side automation and RAG against Obsidian vaults.
I wish I could use Obsidian to edit single markdown files.
If my project has a readme.md I don't want to create an obsidian vault with its configuration files in my project, just to open it.
Yeah we'll add that at some point.
It's a bit trickier than it seems because a lot of Obsidian configuration and app functionality is vault-specific. E.g. what theme should be used? What plugins should be available? Does autocomplete for [[links]] or properties do anything? Etc.
VSCode opens single files outside of projects. What do they do? Personally I wouldn’t mind if it just defaulted to the settings of the last-used vault.
If you don't have a window open, then VSCode opens with no active workspace. There are no workspace settings at all, and there is no file tree. But since VSCode has user level settings, these are what is used, including theming/etc.
If you have a window open, the file is opened to the workspace for that window. You can see this in action because the "Trust" dialog specifically says that you're trying to open untrusted files into a trusted workspace.
maybe you're overthinking it a little. You could make it of a default setup like the one you use for the sandbox, or some curated fast-loading one
Oh wow thats good timing. I DIY’ed a workaround for this only last week for my openclaw instance. Happy to change it to this! https://jakobs.dev/granular-notes-access-limiting-openclaw-b...
Isn't there a script or a plugin to sync your vault to github, already? (may be even to sync several vaults, for example to share vaults between colleagues)
This tool should finally make it possible to setup a good web interface to my obsidian notes. I have a hacky setup using github as the backend storage system but its slow.
Ive been surprised at how few people are interested in an obsidian browser tool, but its great if I want to read / write notes from a corporate laptop for example.
I just have my vault sitting in Dropbox ... Not sure what I would gain by moving to Sync?
End-to-end encryption, integrated version history, better mobile support, granular control over which settings and files are synced to each device.
And generally help the continued development of Obsidian so we can stay 100% user-supported.
Access on mobile would be main reason. Perhaps that’s an iOS limitation, and Dropbox on Android is just a perfect replacement.
It would be good since I don't use obsidian on my desktop but I do on my phone, so that way I can use it for syncing and then open the documents on Neovim on my desktop
Nice! I rely on Obsidian a lot for syncing knowledge while working with Claude agents, such as storing research and daily logs to catch up on the prior day’s work. It already works quite well with a custom skill that I build, but this may make the workflow smoother.
I also built a cli tool to index embeddings in LanceDB and do semantic search. It helps agents create better internal links between notes. https://github.com/ravila4/obsidian-semantic-search
Can you share more details on your setup with Claude Code ?
How does this affect your token/quota usage?
Finally! I had to set up a container with X on my headless server to get a few text files reliably synced, crazy stuff.
Ha! Just yesterday I set up a git repo to sync my Obsidian vault with my Ubuntu VPS for LLM use. Part of me wishes this had come out one day sooner, though honestly, I've grown to like the git workflow. The deal-breaker is mobile: it just doesn't play nicely there, so I'll keep using native sync for that.
For some reason obsidian sync consitently empties random recently opened notes for me. I think it might be some kind of race condition between icloud sync and obsidian sync. File gets touched before obsidian gets to it so the empty note is seen as a new file. That theory doesn't quite hold up though because the same thing happens to me using the android client. Has anyone here had this problem?
I had this happen a bunch when I was using iCloud sync on multiple devices. I think it was mostly solved by setting the directory to “keep downloaded” (right click on it in finder and it’s the second option).
That said, I’ve switched one vault to git and have had no issues there.
This is great, but as convenient as Obsidian Sync is, it'll never replace plain Git (for me) until it has unlimited version history:
> The retention period for your version history depends on your Obsidian Sync plan. On the Standard plan, notes are retained for 1 month, while on the Plus plan, they are kept for 12 months. After this period, older versions of your notes are deleted.
You can use this to sync changes in (near) realtime and then either commit them to git, or use some other mechanism to increase retention.
Then you have two solutions to maintain when one would suffice.
It also won't replace Postgres, because that is also a different thing.
What do you mean? Version history is explicitly a feature of Obsidian Sync: https://help.obsidian.md/Obsidian+Sync/Version+history
Yes, but just because it has version history doesn't mean it is closer to git than to Postgres. You can also do versioning in Postgres. You can even search more easily in the history.
I assume they meant "it will never replace Git for syncing Obsidian".
Great, now it can corrupt my data headlessly too.
Nice to see an official headless option. If anyone is looking to do headless syncing specifically to their own Synology NAS, I created an open-source alternative for that here: https://pypi.org/project/obsidian-synology-sync/
I know this is headless but is there any other reason I should use this over the official Synology drive app?
I've been using Synology Drive to sync Obsidian between different machines and my android phone and it works great. I've never seen a need to use the official sync.
The official Sync is focused on providing a more integrated experience in the Obsidian app
- Built-in version history
- Cross-platform support, especially on mobile
- Fine-grained control (e.g. different theme/plugins/settings per device)
- Sharing your vaults with other users
Synology Drive is a file and folder syncing system.
Obsidian is a note and wiki syncing system.
You should use an obsidian syncing system if you want to sync notes and wikis. You should use a file syncing system if you want to sync files.
This reply does not address parents question at all.
A key feature of Obsidian is that it stores your notes in an open folder structure on your file system.
A very valid question is whether there are benefits to using a special note sync application rather than a standard file system sync application, and if so, what those benefits are.
Why would you use this over plain git in a CI pipeline? Presumably you need your knowledge graph versioned?
iOS makes it painful to use third-party sync protocols and servers, like syncthing can't run in the background, a git sync service can't run in the background, only iCloud gets to run in the background.... and whatever sync protocol the app itself has blessed so it can run immediately on opening the app.
As such, on iOS the native sync is the only one that works cleanly and seamlessly, and so you're incentivized to pay for it.
There was a little while, when dropbox was big, where it seemed like the future of computing would be "your data is in the cloud, and every app you use can share that data, and those two things are independent integrated through some common filesystem layer".
And then it ended up that no, your data's in a cloud-per-service, where your emails live in googles cloud, your documents in microsoft 365's cloud, your images in "adobe creative cloud"'s cloud, your photos in Apple's cloud, your passwords in 1Password's cloud, and your knowledgebase in Obsidian's cloud.
The dream of the filesystem API being able to expand to clouds, of being able to choose dropbox or google or apple as the owner of your data, and other applications seamlessly integrating with any of them, it died with apple making it impossible to offer any sort of generic filesystem API or even background sync.
And so, that's why you'd use obsidian sync over git, because you're cursed with using a phone.
Unless you're saying "why not pay for obsidian sync, but then sync it into a git repo in CI and commit there to see the diffs", not "why not use git as the underlying sync protocol", in which case ignore everything I wrote, you totally could do that.
Gotcha, thanks. I just use git but don’t sync to my iPhone, this helps give context on the value prop there.
If you have automation that dumps things int your vault, that you built with their new CLI (which lets you create/tag docs etc. without running the full electron app), I guess this lets you sync those changes and propagate them to all of your obsidian sync clients also without having to open aforementioned full electron app.
Quoting[1] kepano (CEO of Obsidian) - Why you might use Obsidian Sync headless:
- Automate remote backups
- Automate publishing a website
- Give agentic tools access to a vault without access to your full computer
- Sync a shared team vault to a server that feeds other tools
- Run scheduled automations e.g. aggregate daily notes into weekly summaries, auto-tag, etc
...all while having the speed, privacy, customizability, end-to-end encryption of Obsidian Sync.
To enjoy the native ease of use and security of Obsidian Sync as a human user on your devices; while being able to automate things on a server.
Does the knowledge graph have a function other than to show off how big your vault is?
Only in 2nd-brain mythology, which holds that you'll discover connections between your notes that you didn't realize was there. I think it started as eye candy to confuse prospective users considering Roam Notes. They later did something similar with their "Canvas" feature. So, these are features you get with their lack of coherent vision, rather than basic usability and a safe plugin ecosystem, neither of which Obsidian plans to deliver..
I just use Dropbox with dropsync on my phone. I never use the knowledge graph anyway
What’s the best way to sync Obsidian without upgrading to their paid tier?
For my work notes, which are not allowed to be stored outside company resources, I have set up a git repo and use a plugin that auto commits.
It does not work well for sharing to a mobile env but works great for desktop.
If you’re on Apple devices only, then iCloud sync is free and works on all devices.
I no longer use Obsidian, so not sure what’s the best option for e.g. Linux <-> iOS sync except their service.
I use syncthing to sync my notes between my PC and Laptop. It works pretty well.
I'm quite fond of the obsidian-gut plugin and syncing to a private Forgejo instance.
YES...HA HA HA...YES!
I love this as I can now sync the research I do using an OpenClaw running on an EC2 instance. My setup here: https://x.com/AdilMouja/status/2025266443613319546
Too late
Interesting...I've been thinking for a while that doing instructions and logs through my obsidian notes would be really helpful and a great way to do more agentic work. I've paid for obsidian sync as a way to support their team for the last 3 years, but color me impressed that there are some more tangible benefits to it!
This is huge. I built SidianSidekicks and it is based on git because we don't want to lose your notes and thoughts, but convenience of Obsidan Sync are something that makes everything easy. I get this is in beta, and we will stick to git, but love what they are doing and looking forward to it.
Essentially Sync while you can emulate it on desktop, for mobile it is not good experience without Sync. And we want to have and record our thoughts with us all the time.
what does this mean ? can i self host stuff ?
Fantastic! Now I don't need to run it in a headless xorg session.
Now make Dropbox sync work with iPhone
That will never happen; their only money-making method is to limit the iOS app to sell their cloud. Otherwise, the desktop is already free with your own vault folder.
They are trying their hardest to prevent users from using Google Drive or other services natively. While it is just a small option to add, it will make everyone drop their $4 cloud subscription.
If that were true Obsidian would not allow third-party sync plugins in the official directory, and wouldn't mention third-party options in the official docs:
https://help.obsidian.md/sync-notes
The goal for Obsidian Sync is to be the best option, not the only option.