Headless LiveSync Server Runbook

Companion note for unified-agent-memory-fabric.

Why this exists

The server needs to participate in Obsidian LiveSync without running the Obsidian GUI. The critical idea is path separation: one path for LiveSync runtime state, one path for the actual vault.

Spec

Headless LiveSync on server

Purpose

server participates in the same CouchDB LiveSync network as mac, phone, and iPad without running the Obsidian GUI app.

This lets:

• mobile or mac edits materialize into /srv/vault-write
• cloud agent edits under /srv/vault-write propagate to CouchDB
• gbrain index a filesystem that stays close to current vault reality

Working deployment

Paths

• LiveSync CLI database path: /srv/livesync-db
• Real vault path: /srv/vault-write
• CLI source path: /opt/obsidian-livesync/src/apps/cli
• Node binary: /srv/.nvm/versions/node/v22.21.1/bin/node
• Service file: /etc/systemd/system/livesync-daemon.service

Service command

/srv/.nvm/versions/node/v22.21.1/bin/node \
  /opt/obsidian-livesync/src/apps/cli/dist/index.cjs \
  /srv/livesync-db \
  --vault /srv/vault-write \
  daemon

Systemd checks

systemctl status livesync-daemon --no-pager
journalctl -u livesync-daemon --no-pager -n 60

Expected log lines:

[Daemon] Mirror scan complete
[Daemon] LiveSync mode: restoring sync settings and starting _changes feed
[Daemon] LiveSync active

Root cause of earlier failures

The failed attempts used the actual vault as the CLI database path. That collapsed these two roles:

• CLI local database/runtime state
• real Obsidian vault files

That produced confusing legacy-couchdb migration behavior and unreliable daemon startup.

The fix was to create a separate database directory and pass the real vault through --vault.

Verified behavior

server-written lines appeared on mac and mobile without a git commit:

• NATIVE-LIVESYNC-SEPARATE-DB TEST 21:08:41
• VERBOSE-WATCH-TEST 21:10:50

This verifies server filesystem to CouchDB to clients.

Remaining verification

Make a small edit from mac or mobile, then check on server:

grep -R "some unique test string" /srv/vault-write

This verifies clients to CouchDB to server filesystem.

Do not do these

• Do not point cloud agents at /srv/livesync-db.
• Do not use /srv/vault-write as both database path and vault path.
• Do not patch LiveSync JSON settings by guessing. Read docs or source first.
• Do not commit large deletion sets from git status unless deletion intent is confirmed.

Durability gap

The CLI source currently lives under /opt/obsidian-livesync. Move it to a durable path before considering this production-hardened, for example:

/srv/services/obsidian-livesync

Then update the systemd service to point there.

---

Setup notes

server headless LiveSync setup notes

Verified command

export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"
cd /opt/obsidian-livesync/src/apps/cli
node dist/index.cjs /srv/livesync-db --vault /srv/vault-write daemon

Required settings file

Path:

/srv/livesync-db/.livesync/settings.json

Do not commit this file because it contains CouchDB credentials.

Minimum required fields:

{
  "remoteType": "couchdb",
  "couchDB_URI": "https://couchdb.livesync.goku.codes",
  "couchDB_USER": "admin",
  "couchDB_PASSWORD": "REDACTED",
  "couchDB_DBNAME": "vault-write",
  "isConfigured": true,
  "liveSync": true,
  "syncOnStart": true,
  "syncOnSave": true,
  "syncOnEditorSave": true,
  "keepReplicationActiveInBackground": true,
  "encrypt": false,
  "usePluginSync": true,
  "usePluginSyncV2": true,
  "customChunkSize": 60,
  "handleFilenameCaseSensitive": false,
  "deviceAndVaultName": "server-headless-livesync"
}

Verification

Write a test line on server:

echo "server test $(date -u +%H:%M:%S)" >> /srv/vault-write/TEST-LIVESYNC-FROM-ORACLE.md

Expected: it appears on mac and mobile without git commit.

---

Minimal service shape

[Unit]
Description=Self-hosted LiveSync CLI Daemon
After=network-online.target
 
[Service]
Type=simple
WorkingDirectory=/opt/obsidian-livesync
ExecStart=/usr/bin/node dist/index.cjs /srv/livesync-db --vault /srv/vault-write daemon
Restart=always
RestartSec=5
 
[Install]
WantedBy=multi-user.target

Credentials belong in an environment file or local settings store, not in the public note.

For the full proposal and design decisions that led to this setup, see unified-agent-memory-openspec-plan.