Server and agent projection

Approval-gated

Use Headless only when a server or agent needs a filesystem projection through Obsidian Sync without desktop Obsidian.

Prerequisites

• Dedicated least-privilege OS identity and filesystem allowlist.
• Node.js 22+ and obsidian-headless installed.
• Approved managed account alias and active Sync entitlement read back without secrets.
• Recoverable source backup.
• One Sync method per device; never desktop Sync and Headless Sync on the same device.
• Named writer, reviewer, evidence owner, and rollback owner.

Safe sequence

1. Read-only discovery: after approved interactive login, inventory remote and local mappings with ob sync-list-remote and ob sync-list-local.
2. Stop for exact approval before setup, mode/config changes, or continuous Sync.
3. Bind only the approved remote vault and local path. Keep passwords interactive.
4. Read configuration and status before execution.
5. Run a bounded canary under supervision before a continuous process.
6. Verify source and destination status, then read the canary from a second device by exact path and compare bytes/content and SHA-256.
7. Check conflicts, deletions, and unexpected files.
8. Only then enable the approved supervised schedule or service.

External tools may edit synchronized Markdown only under a separately approved writer policy. This is filesystem work, not an ob note-edit, metadata-cache, command-palette, or plugin-graph API.

Supervision

Continuous operation requires a process supervisor, bounded redacted logs, health checks, restart limits, and a documented stop/disable procedure. A running process or ob sync-status alone is not convergence proof.

Authority boundary

The projection is not Agent HQ, an accepted Score, or trusted-wiki Gold. Never copy a live SQLite database to populate the server.

Rollback

Stop the supervised process, preserve source/destination status and conflict/deletion evidence, restore only from the approved recoverable backup under exact scope approval, and repeat second-device readback.

Source: Headless Sync, retrieved 2026-08-29 EDT.