livesync-agent

Headless agent to sync Obsidian vaults bidirectionally using CouchDB.

🇪🇸 Spanish docs: README_es.md

0) Install the Obsidian plugin first

This agent is designed to work with Self-hosted LiveSync.

Install plugin in Obsidian from:

• https://obsidian.md/es/plugins?search=Self-hosted%20LiveSync

1) Deploy CouchDB with HTTPS (Traefik + Swarm)

Use the included stack:

• deploy/couchdb.yaml
• deploy/README.md

Quick deploy:

printf 'admin' | docker secret create couchdb_user -
printf 'CHANGE_ME_STRONG_PASSWORD' | docker secret create couchdb_password -
docker stack deploy -c deploy/couchdb.yaml couchdb

2) Install livesync-agent

Option A: release installer script (Linux x86_64)

curl -fsSL https://raw.githubusercontent.com/aitorroma/obsidian-livesync-agent/main/scripts/install.sh | bash

Option B: Homebrew (macOS/Linux, builds from source)

Tap and install:

brew tap aitorroma/obsidian-livesync-agent https://github.com/aitorroma/obsidian-livesync-agent
brew install livesync-agent

Install latest main version (source build):

brew install --HEAD aitorroma/obsidian-livesync-agent/livesync-agent

Option C: from source

cargo build --release
./target/release/livesync-agent --help

3) Configure

Interactive setup:

livesync-agent setup

Default config path: ~/.livesync-agent/config.toml (directory is created automatically).

Then run one cycle:

livesync-agent sync-once

Or daemon mode:

livesync-agent daemon --interval-seconds 30

Install as systemd user service (and start immediately):

livesync-agent daemon --interval-seconds 30 --install

If you're in a non-interactive shell (for example su - or some containers), auto-start may fail because the user session bus is unavailable. In that case the service file is still installed and you can enable it later from a normal login session:

systemctl --user daemon-reload
systemctl --user enable --now livesync-agent.service

Headless server tip (one-time):

sudo loginctl enable-linger $USER

Releases

GitHub Actions release workflow:

• File: .github/workflows/release.yml
• Trigger: push tag v* (example: v0.1.1)
• Build targets: Linux x86_64 (musl + gnu)

Create release:

git tag v0.1.1
git push origin v0.1.1

Assets uploaded:

• livesync-agent-<tag>-x86_64-unknown-linux-musl.tar.gz (portable, preferred by installer)
• livesync-agent-<tag>-x86_64-unknown-linux-gnu.tar.gz
• SHA256SUMS