OLive

OLive, short for 'Obsidian Live', is a production-oriented fork of the existing headless CLI in Self-hosted LiveSync. Upstream already provides the essential headless synchronisation pipeline: Node.js filesystem adapters, a local PouchDB, CouchDB replication, encryption, chunking, conflict handling, filesystem watching, and Docker packaging. OLive reuses that implementation rather than creating another LiveSync protocol or synchronisation engine.

This fork adds the operational layer required to run that CLI as a dependable, unattended Linux service. Its focus is supervision, safe vault access, recovery, diagnostics, installation, and compatibility validation.

The primary use case is an agent running in a headless virtual machine. OLive keeps the agent's local Markdown vault synchronised without requiring the Obsidian application on that machine. Changes made by the agent become visible to every connected Obsidian user, and user changes become available to the agent, including attached images that the agent can inspect. In this workflow, Obsidian acts as the human-facing proxy for supplying content to agents and receiving their results.

OLive uses the upstream LiveSync protocol and shared services to synchronise bidirectionally with CouchDB. The headless agent and Obsidian plug-in use the same livesync-commonlib submodule, Metadata and Chunks format, encryption implementation, conflict handling, and replication services.

• A supervised olive daemon with explicit lifecycle states, bounded retry and back-off, graceful shutdown, and recovery after ordinary outages.
• Persistent status, health checks, diagnostics, conflict inspection, and suspension controls for unattended operation.
• Exclusive database and vault ownership locks, atomic filesystem writes, symlink protection, ignore rules, and a vault-local recovery area for reflected deletions.
• Separate vault, local PouchDB, configuration, and runtime-state paths.
• Fast Setup (Simple Fetch), explicit first-run policies, recovery flags, and guarded remote rebuilds.
• An Arch Linux-oriented installer, XDG profile layout, hardened systemd user service, checksummed release archives, and a non-root container.
• Long-running compatibility tests between two headless agents and between the CLI and a real Obsidian instance, including encryption and Path Obfuscation.
• A documented process for regularly integrating changes from upstream.

For occasional one-shot commands or basic headless synchronisation, the upstream CLI may already be sufficient. OLive is intended for installations where the agent must run continuously, survive restarts and network failures, expose actionable state, and preserve data when a safe automatic decision is not possible.

Linux vault A
    ↕ filesystem watcher and atomic reflection
Headless agent + local PouchDB
    ↕ LiveSync replication
CouchDB containing Metadata and Chunks
    ↕ LiveSync replication
Obsidian plug-in + its local database
    ↕ Obsidian vault API
Obsidian vault B

Files are represented by Metadata and referenced Chunks. Raw file content is not stored directly in Metadata documents.

The production profile is Arch Linux, Node.js 24, CouchDB, and visible vault files. Continuous and periodic bidirectional synchronisation, V1 and V2 end-to-end encryption, Path Obfuscation with V2, Markdown files, binary files, conflicts, and Fast Setup have compatibility coverage.

The following capabilities are not part of the stable headless profile:

• Hidden File Sync and Customisation Sync are not supported by the agent.
• P2P one-shot commands remain experimental.
• An unattended P2P daemon is not supported.
• S3-compatible Object Storage has one-shot test coverage only.

See the complete compatibility matrix before using a capability outside the production profile.

Install the build and runtime prerequisites:

sudo pacman -S --needed base-devel git nodejs npm

Clone the fork with its shared-library submodule, and install a user service:

git clone --recurse-submodules https://github.com/bitbeamer/olive.git
cd olive

bash src/apps/cli/deploy/install.sh \
  --profile main \
  --vault /home/alice/Documents/Obsidian/Main \
  --bootstrap merge

The installer creates an unconfigured profile but does not start it. Export a Setup URI from the Self-hosted LiveSync plug-in on another device, and import it into the agent:

~/.local/bin/olive \
  ~/.local/share/olive/main \
  --settings ~/.config/olive/main/settings.json \
  setup 'obsidian://setuplivesync?settings=...'

Validate and start the profile:

~/.local/bin/olive \
  ~/.local/share/olive/main \
  --vault /home/alice/Documents/Obsidian/Main \
  --settings ~/.config/olive/main/settings.json \
  doctor

systemctl --user enable --now olive@main.service
journalctl --user -u olive@main.service -f

Use --bootstrap remote-first for an empty secondary vault which should be initialised with Fast Setup (Simple Fetch). Use --bootstrap merge to preserve and reconcile existing local and remote files. Use --bootstrap refuse when an uninitialised profile must not start automatically.

The full procedure, including updates, release archives, and removal, is in INSTALL.md.

Common commands are:

# Persisted agent state
olive ~/.local/share/olive/main status

# Configuration, paths, permissions, and state checks
olive ~/.local/share/olive/main \
  --vault /home/alice/Documents/Obsidian/Main \
  --settings ~/.config/olive/main/settings.json \
  doctor

# Database conflicts
olive ~/.local/share/olive/main conflicts

# Suspend or resume through redflag.md
olive ~/.local/share/olive/main \
  --vault /home/alice/Documents/Obsidian/Main suspend
olive ~/.local/share/olive/main \
  --vault /home/alice/Documents/Obsidian/Main resume

Runtime states include STARTING, FETCHING, RECONCILING, RUNNING, DEGRADED, SUSPENDED, STOPPING, STOPPED, and FAILED. A transient CouchDB outage leaves the process alive in a degraded state so it can retry. Authentication failures and unsafe configuration stop the agent for operator attention.

See Headless agent recovery before using fetch or remote-rebuild operations.

The default main profile uses:

~/.local/bin/olive
~/.local/share/olive/main/                     local PouchDB and runtime state
~/.config/olive/main/settings.json             LiveSync settings
~/.config/olive/main/agent.env                 systemd profile
~/.config/systemd/user/olive@.service

Multiple profiles may run simultaneously when every profile has distinct vault and local database paths.

This repository continues to build the Self-hosted LiveSync community plug-in. The original plug-in documentation remains applicable to Obsidian clients:

• Quick Setup
• CouchDB server setup
• Settings reference
• Fast Setup
• Troubleshooting
• Peer-to-Peer Synchronisation

The former plug-in-focused repository introduction is preserved as the upstream README. Its Japanese and Chinese translations are also retained.

The plug-in is not compatible with the official Obsidian Sync service. Do not enable multiple synchronisation systems for the same vault.

This fork intentionally keeps the upstream Git history and the shared livesync-commonlib submodule. Fork-only daemon policy remains under src/apps/cli; generic protocol and compatibility fixes should remain suitable for upstream contribution.

A scheduled workflow performs a read-only trial merge of current upstream/main, followed by checks, unit tests, and builds. Actual upstream updates are integrated through reviewed commits and include both plug-in and agent compatibility verification.

See Fork delta and upstream maintenance for the current baseline, intentional differences, and update procedure.

Initialise the submodule and dependencies, then run the principal gates:

git submodule update --init --recursive
npm ci
npm run build
npm run check
npm run test:unit
npm --prefix src/apps/cli run build
npm --prefix src/apps/cli run test:unit

See the development guide and the headless runtime proposal for architecture, testing, and release details.

This fork builds on the work of the Self-hosted LiveSync maintainer, contributors, sponsors, and the livesync-commonlib contributors. The upstream contributor history remains part of this repository.

Licensed under the MIT Licence.