Obsidian Headless Sync — macOS LaunchAgent

README.md

Obsidian Headless Sync — macOS LaunchAgent

A macOS LaunchAgent plist that runs Obsidian Headless Sync continuously in the background, starting automatically at login.

Do not run both the Obsidian desktop app’s built-in Sync and Headless Sync on the same machine. This can cause data conflicts.

Prerequisites

1. Install the headless client:

   npm install -g obsidian-headless

2. Log in and link your local vault to a remote vault (one-time):

   ob login
   cd /path/to/local/vault
   ob sync-setup --vault "Your Remote Vault"

Installation

1. Edit md.obsidian.headless-sync.plist:

   • Set the path to ob (run npm prefix -g to find it).
   • Set the path to your local vault directory.

2. Copy the plist and load the agent:

   cp md.obsidian.headless-sync.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/md.obsidian.headless-sync.plist

Usage

Verify the agent is running:

launchctl list | grep obsidian

Tail the logs:

tail -f /tmp/obsidian-headless-sync.log
tail -f /tmp/obsidian-headless-sync.err

Stop the agent:

launchctl unload ~/Library/LaunchAgents/md.obsidian.headless-sync.plist

Behavior

• The agent starts at login and auto-restarts on crash.
• Logs are written to /tmp/obsidian-headless-sync.log (stdout) and /tmp/obsidian-headless-sync.err (stderr).

md.obsidian.headless-sync.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>

  <key>Label</key>
  <string>md.obsidian.headless-sync</string>

  <key>ProgramArguments</key>
  <array>
    <!-- Replace with your output of npm prefix -g -->
    <string>/opt/homebrew/bin/ob</string>
    <string>sync</string>
    <string>--path</string>
    <!-- Replace with your local vault path -->
    <string>/Users/platyhsu/roam/</string>
    <string>--continuous</string>
  </array>

  <key>RunAtLoad</key>
  <true/>

  <key>KeepAlive</key>
  <dict>
    <key>SuccessfulExit</key>
    <false/>
  </dict>

  <key>StandardOutPath</key>
  <string>/tmp/obsidian-headless-sync.log</string>

  <key>StandardErrorPath</key>
  <string>/tmp/obsidian-headless-sync.err</string>

  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>

</dict>
</plist>