Syncing Obsidian to a Headless Server

Dear Readers,

last piece of the puzzle: getting Obsidian synced to the server so agents can read and write to the vault directly.

Why Run Obsidian on a Server?

#

Obsidian Sync only works through the Obsidian app — there’s no standalone sync CLI or API. To get vault data onto a headless server, you need to run Obsidian itself. The LinuxServer.io Docker image handles this by running Obsidian in a virtual framebuffer with a web-based VNC interface.

Docker Setup

#

# /root/obsidian/docker-compose.yml
services:
  obsidian:
    image: lscr.io/linuxserver/obsidian:latest
    container_name: obsidian
    environment:
      - PUID=0
      - PGID=0
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
    ports:
      - "127.0.0.1:3000:3000"
      - "127.0.0.1:3001:3001"
    shm_size: "1gb"
    restart: unless-stopped

Few things to note:

• Ports bound to localhost — the web UI shouldn’t be exposed to the internet
• shm_size: "1gb" — Obsidian runs in Chromium under the hood, it needs the shared memory
• Volumes — ./config holds the full Obsidian data directory, vaults and all

Start it:

cd /root/obsidian
docker compose up -d

Initial Login via SSH Tunnel

#

The web UI only listens on localhost, so use an SSH tunnel:

ssh -L 3000:127.0.0.1:3000 root@your-server-ip

Open http://localhost:3000 in your browser. You’ll see Obsidian running in a web viewer. Log into your Obsidian account, enable Sync, and select your vault. Once the initial sync finishes, the vault lives at:

/root/obsidian/config/patrik/

After that you can close the tunnel. Obsidian runs headlessly and keeps syncing in the background.

Giving Agents Vault Access

#

Point an OpenClaw agent’s workspace at the synced vault:

{
  "id": "pa",
  "name": "PA",
  "default": true,
  "workspace": "/root/obsidian/config/patrik",
  "model": "anthropic/claude-haiku-4-5-20251001"
}

The agent can now read and write to your vault. Create a SOUL.md in the vault root for agent personality and instructions — it syncs to all devices via Obsidian Sync.

The PA Agent

#

My PA agent is set up to:

1. Ask two intake questions on every new topic (what category + new or existing note)
2. File notes into the right vault folder
3. Read existing notes for context
4. Use Haiku for speed and cost efficiency

The agent’s SOUL.md, IDENTITY.md, and AGENTS.md all live in the vault root. Since they sync via Obsidian, I can tweak agent behavior from my phone and the server picks up changes within seconds.

Vault Structure

#

Organized by category:

patrik/
  SOUL.md
  IDENTITY.md
  AGENTS.md
  Personal Projects/
    clawd.it/
      Installation Guide.md
      Credentials.md
  Work/
  Learning/
  ...

The agent understands this structure and routes new content accordingly.

What This Enables

#

Send a message to the Telegram bot like:

“Save this idea: build a voice interface for OpenClaw using Whisper”

…and it ends up as a note in the right folder in your vault, synced to all devices within seconds.

The agent becomes a bridge between messaging apps and the knowledge base — reads existing notes for context, writes new ones in your organizational style, and everything stays in sync through Obsidian.

With the vault synced, agents can read and write to your knowledge base directly. Future posts in this series will cover vault structure strategies, multi-vault setups, and agent-driven note organization.