Headless sync

Courier normally syncs from inside Obsidian. It can also sync a vault on a machine that never opens Obsidian — a small always-on server, a NAS, or a laptop that spends the day with Obsidian closed: install Courier’s command-line tool, and it keeps that folder in sync in the background.

When you would want it

• The vault lives on a machine that is always on, and its copy should stay current even though the machine runs no Obsidian.
• A script, a backup job or an AI assistant edits files on that machine directly, and those changes should reach your devices.
• Your laptop rarely has Obsidian open, but the changes you make on your phone during the day should still land on it.

Getting started

Take the way you prefer: the desktop app installs and runs the tool for you, or you use the command line on Linux / macOS or Windows. Each tab is one complete path.

Desktop app

1. Install the tool. The page downloads it and verifies the release before using it.
2. Sign in with the server address and a user key — the same kind of key the Obsidian plugin uses.
3. Add a vault: pick the remote vault, the local folder, the vault password, and a device name for this machine.
4. Start it. Each vault has its own row and its own start button; it keeps running in the background after you close the app.

Linux / macOS

# install (once)
curl -fL https://github.com/ah-yu/courier/raw/main/install.sh | sh

# sign in: your server address and user key
courier-cli register --server https://YOUR_IP:8443 \
  --user-key ck_xxx -n "NAS"

# bind: the vault id is in the desktop app's vault list; point the path at your folder
courier-cli vault connect --id YOUR_VAULT_ID --path ~/vault \
  --password YOUR_VAULT_PASSWORD

# start syncing
courier-cli run --vault YOUR_VAULT_ID

Windows

# install (once)
irm https://github.com/ah-yu/courier/raw/main/install.ps1 | iex

# sign in: your server address and user key
courier-cli register --server https://YOUR_IP:8443 `
  --user-key ck_xxx -n "NAS"

# bind: the vault id is in the desktop app's vault list; point the path at your folder
courier-cli vault connect --id YOUR_VAULT_ID --path "$HOME\vault" `
  --password YOUR_VAULT_PASSWORD

# start syncing
courier-cli run --vault YOUR_VAULT_ID

courier-cli status lists every bound vault with its process and its conflict copies. One process syncs one vault, so three vaults mean three processes.

How it works with Obsidian

It runs the same engine as the plugin, so the rules are the same: changes are pushed as they happen, the remote version wins a conflict, and the local one is parked beside the note as *.conflict.*.

It does not touch your Obsidian settings: only Obsidian can read the .obsidian folder, so settings sync stays with the plugin.

One writer per vault. If Obsidian has the vault open and the command-line tool is started too, whichever started first keeps syncing and the other waits — no error, and it takes over as soon as the first one stops.

The desktop app remembers each vault’s switch too: a vault you left running comes back after a restart.