integration-obsidian

name

integration-obsidian

description

Connect an Obsidian vault to a self-hosted Hermes agent over SSH. Obsidian is a local desktop app — this skill picks between three honest paths: (A) vault-file mode via git/rclone/Syncthing on the VPS (preferred for headless agents), (B) the community Local REST API plugin over a private tunnel (Tailscale / Cloudflare Tunnel), (C) the mcp-obsidian stdio wrapper. Idempotent and rollback-safe. Works from Claude Code, Codex, Cursor, Hermes itself, and any AI agent.

/integration-obsidian — connect an Obsidian vault to a remote Hermes (SSH-first)

You are the engineer connecting an Obsidian vault to a self-hosted Hermes agent on the user's VPS. You (the AI agent — Hermes, Claude Code, Codex, Cursor, Gemini, any of them) work over SSH as root against the VPS. Every command in this skill runs on the VPS, not on the user's laptop.

Do everything autonomously; stop only for things a machine cannot do — installing the Local REST API plugin in the desktop app, starting an OS-level tunnel (Tailscale / Cloudflare Tunnel), or granting the git remote push access.

Honest picture (verified 2026-06): Obsidian ships no first-party MCP and no first-party API. Two community pieces exist:

• Local REST API plugin (coddingtonbear/obsidian-local-rest-api) — HTTPS server running inside the desktop app, default https://127.0.0.1:27124 (self-signed cert) or http://127.0.0.1:27123. Bearer-auth. Only reachable when the desktop app is open — kills the connection when the user closes their laptop.
• mcp-obsidian (MarkusPfundstein/mcp-obsidian) — stdio MCP wrapper around the Local REST API. Same reachability constraint.

Neither is viable for a always-on VPS agent unless the user pipes their laptop's localhost to the VPS via a private tunnel. So Path A (vault-as-files on the VPS) is the default for headless deployments — the agent reads and writes markdown, and Obsidian on the laptop syncs via git / Obsidian Sync / Syncthing / iCloud. Pick per the user's sync tool.

---

Before you start — gather (ask once, in one batch)

Variable	What	Where to get it
$VPS_IP	IP/hostname of the VPS running Hermes	User's hosting dashboard
$VPS_USER	SSH user (typically root)	User's hosting dashboard
$OBSIDIAN_PATH	Path selector: A (vault-file), B (Local REST via tunnel), or C (mcp-obsidian)	Ask the user
$OBSIDIAN_VAULT_DIR	(Path A) Absolute vault dir on the VPS (e.g. /opt/data/vault)	User's choice
$OBSIDIAN_SYNC_MODE	(Path A) git | syncthing | rclone | manual	User's choice; git is easiest to automate
$OBSIDIAN_GIT_REMOTE	(Path A + git) [e-mail]:user/vault.git (private repo)	User's provider
$OBSIDIAN_API_URL	(Path B/C) Tunneled URL, e.g. https://vault.tail-xxxx.ts.net:27124 or http://obsidian.laptop.internal:27123	Tailscale MagicDNS / Cloudflare Tunnel dashboard
$OBSIDIAN_API_KEY	(Path B/C) API key from Local REST API plugin settings	Obsidian desktop -> Settings -> Community plugins -> Local REST API -> API Key
$OBSIDIAN_TLS_MODE	(Path B/C) insecure (self-signed cert, default plugin behavior) | strict (user installed the plugin's CA cert on the VPS)	Advanced users only pick strict
$WRITES_ACKNOWLEDGED	Set to 1 to confirm the agent may CREATE and MODIFY notes (Path A auto-commits, Path B/C uses PATCH endpoints)	Consent gate — data destination is user notes

Confirm SSH access before doing anything:

ssh -o StrictHostKeyChecking=accept-new -o BatchMode=yes \
    "$VPS_USER@$VPS_IP" "echo ok" 2>&1 | grep -q '^ok$' \
  || { echo "ABORT: SSH to $VPS_USER@$VPS_IP failed. Run /setup-ssh-keys first."; exit 1; }

---

Step 1 — verify Hermes is reachable on the VPS

ssh "$VPS_USER@$VPS_IP" '
  set -e
  if command -v hermes >/dev/null 2>&1; then
    hermes --version
  elif docker ps --format "{{.Names}}" | grep -q hermes; then
    AGENT=$(docker ps --filter name=hermes --format "{{.Names}}" | head -1)
    docker exec "$AGENT" hermes --version
  else
    echo "FAIL: hermes not found on host or in container"; exit 1
  fi
' || { echo "ABORT: Hermes is not installed/running. Run /hermes-install first."; exit 1; }

Expected: 0.15.x or 0.17.x.

---

Step 2 — idempotency check (skip if already wired)

ALREADY=$(ssh "$VPS_USER@$VPS_IP" "grep -c '^OBSIDIAN_PATH=' ~/.hermes/.env 2>/dev/null" || echo 0)
if [ "$ALREADY" -gt 0 ] && [ "${FORCE:-0}" != "1" ]; then
  PREV=$(ssh "$VPS_USER@$VPS_IP" "grep '^OBSIDIAN_PATH=' ~/.hermes/.env | cut -d= -f2")
  echo "Obsidian is already wired via Path $PREV. Set FORCE=1 to rewire."
  exit 0
fi

---

Step 3 — HARD GATE: validate + live pre-flight per chosen path

Do NOT write anything until the checks for the chosen path pass.

[ "${WRITES_ACKNOWLEDGED:-0}" = "1" ] || {
  echo "ABORT: WRITES_ACKNOWLEDGED=1 required. The agent will create and modify notes in the vault."; exit 1;
}

case "$OBSIDIAN_PATH" in
  A|B|C) ;;
  *) echo "ABORT: OBSIDIAN_PATH must be A, B, or C."; exit 1 ;;
esac

Path A — vault-as-files

if [ "$OBSIDIAN_PATH" = "A" ]; then
  [ -n "$OBSIDIAN_VAULT_DIR" ] || { echo "ABORT: OBSIDIAN_VAULT_DIR required."; exit 1; }
  case "$OBSIDIAN_SYNC_MODE" in
    git|syncthing|rclone|manual) ;;
    *) echo "ABORT: OBSIDIAN_SYNC_MODE must be git|syncthing|rclone|manual."; exit 1 ;;
  esac
  # If git mode, verify remote access without cloning yet
  if [ "$OBSIDIAN_SYNC_MODE" = "git" ]; then
    [ -n "$OBSIDIAN_GIT_REMOTE" ] || { echo "ABORT: OBSIDIAN_GIT_REMOTE required for git sync."; exit 1; }
    ssh "$VPS_USER@$VPS_IP" "GIT_SSH_COMMAND='ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new' git ls-remote '$OBSIDIAN_GIT_REMOTE' HEAD" >/dev/null 2>&1 \
      || { echo "ABORT: cannot reach $OBSIDIAN_GIT_REMOTE from VPS. Add the VPS SSH key as a deploy key on the vault repo first."; exit 1; }
    echo "OK: git remote reachable from VPS."
  fi
fi

Path B — Local REST API over tunnel

if [ "$OBSIDIAN_PATH" = "B" ]; then
  [ -n "$OBSIDIAN_API_URL" ] || { echo "ABORT: OBSIDIAN_API_URL required."; exit 1; }
  [ "${#OBSIDIAN_API_KEY}" -ge 20 ] || { echo "ABORT: OBSIDIAN_API_KEY too short."; exit 1; }
  case "$OBSIDIAN_TLS_MODE" in insecure|strict) ;; *) OBSIDIAN_TLS_MODE=insecure ;; esac
  CURL_TLS=$([ "$OBSIDIAN_TLS_MODE" = "insecure" ] && echo "-k" || echo "")
  # Live pre-flight: GET / on the plugin returns a small JSON status block
  HTTP=$(ssh "$VPS_USER@$VPS_IP" "curl -sS $CURL_TLS -o /tmp/obs-preflight.json -w '%{http_code}' \
    -H 'Authorization: Bearer $OBSIDIAN_API_KEY' '$OBSIDIAN_API_URL/'" 2>/dev/null || echo 000)
  case "$HTTP" in
    200) echo "OK: Local REST API reachable at $OBSIDIAN_API_URL." ;;
    401|403) echo "ABORT: $HTTP — API key rejected. Copy from Obsidian -> Settings -> Local REST API."; exit 1 ;;
    000) echo "ABORT: no response. Confirm the tunnel is up AND Obsidian desktop is running with the plugin enabled."; exit 1 ;;
    *)   echo "ABORT: unexpected HTTP $HTTP from Obsidian API."; exit 1 ;;
  esac
  ssh "$VPS_USER@$VPS_IP" "rm -f /tmp/obs-preflight.json"
fi

Path C — mcp-obsidian stdio wrapper

if [ "$OBSIDIAN_PATH" = "C" ]; then
  # Path C is Path B + an MCP wrapper — reuse Path B's checks
  [ -n "$OBSIDIAN_API_URL" ] || { echo "ABORT: OBSIDIAN_API_URL required (mcp-obsidian wraps the same REST API)."; exit 1; }
  [ "${#OBSIDIAN_API_KEY}" -ge 20 ] || { echo "ABORT: OBSIDIAN_API_KEY too short."; exit 1; }
  # Same pre-flight against the underlying REST API
  CURL_TLS=$([ "${OBSIDIAN_TLS_MODE:-insecure}" = "insecure" ] && echo "-k" || echo "")
  HTTP=$(ssh "$VPS_USER@$VPS_IP" "curl -sS $CURL_TLS -o /dev/null -w '%{http_code}' \
    -H 'Authorization: Bearer $OBSIDIAN_API_KEY' '$OBSIDIAN_API_URL/'" 2>/dev/null || echo 000)
  [ "$HTTP" = "200" ] || { echo "ABORT: underlying REST API not reachable ($HTTP). Fix Path B first."; exit 1; }
  echo "OK: underlying REST API reachable — mcp-obsidian can wrap it."
fi

---

Step 4 — DRY RUN preview (always show before writing)

cat <<EOF
DRY RUN — the following will happen on $VPS_USER@$VPS_IP:
  1. Write OBSIDIAN_PATH ($OBSIDIAN_PATH) + path-specific config to ~/.hermes/.env
  2. chmod 600 ~/.hermes/.env
$( [ "$OBSIDIAN_PATH" = "A" ] && echo "  3. Prepare vault dir $OBSIDIAN_VAULT_DIR; set up $OBSIDIAN_SYNC_MODE sync" )
$( [ "$OBSIDIAN_PATH" = "A" ] && [ "$OBSIDIAN_SYNC_MODE" = "git" ] && echo "     Clone $OBSIDIAN_GIT_REMOTE into $OBSIDIAN_VAULT_DIR (if empty)" )
$( [ "$OBSIDIAN_PATH" = "A" ] && echo "     Document filesystem contract at /opt/data/obsidian-vault.md" )
$( [ "$OBSIDIAN_PATH" = "B" ] && echo "  3. Document REST surface at /opt/data/obsidian-rest.md" )
$( [ "$OBSIDIAN_PATH" = "C" ] && echo "  3. Register MCP: hermes mcp add obsidian --command uvx --args mcp-obsidian" )
$( [ "$OBSIDIAN_PATH" = "C" ] && echo "     Warm the uvx cache once to avoid first-call timeout" )
  4. Reload gateway: hermes gateway stop && hermes gateway run
  5. Verify env loaded: env | grep -c '^OBSIDIAN_' inside the gateway
  6. Path-specific smoke test (write test-note.md, verify visible; or GET /vault/)

Secrets are NEVER printed in plaintext.
EOF

Wait for user confirmation (or skip if AUTO_APPROVE=1).

---

Step 5 — write the secrets (chmod 600, no echo, no logging)

ssh "$VPS_USER@$VPS_IP" "hermes config set OBSIDIAN_PATH '$OBSIDIAN_PATH'"

case "$OBSIDIAN_PATH" in
  A)
    ssh "$VPS_USER@$VPS_IP" "
      hermes config set OBSIDIAN_VAULT_DIR '$OBSIDIAN_VAULT_DIR'
      hermes config set OBSIDIAN_SYNC_MODE '$OBSIDIAN_SYNC_MODE'
      $( [ -n "$OBSIDIAN_GIT_REMOTE" ] && echo "hermes config set OBSIDIAN_GIT_REMOTE '$OBSIDIAN_GIT_REMOTE'" )
    "
    ;;
  B|C)
    ssh "$VPS_USER@$VPS_IP" "
      hermes config set OBSIDIAN_API_URL '$OBSIDIAN_API_URL'
      hermes config set OBSIDIAN_API_KEY '$OBSIDIAN_API_KEY'
      hermes config set OBSIDIAN_TLS_MODE '${OBSIDIAN_TLS_MODE:-insecure}'
    "
    ;;
esac

ssh "$VPS_USER@$VPS_IP" "chmod 600 ~/.hermes/.env"

Verify (returns 1 per key, NEVER values):

case "$OBSIDIAN_PATH" in
  A) KEYS="OBSIDIAN_PATH OBSIDIAN_VAULT_DIR OBSIDIAN_SYNC_MODE" ;;
  B|C) KEYS="OBSIDIAN_PATH OBSIDIAN_API_URL OBSIDIAN_API_KEY OBSIDIAN_TLS_MODE" ;;
esac
for K in $KEYS; do
  N=$(ssh "$VPS_USER@$VPS_IP" "grep -c '^$K=' ~/.hermes/.env" || echo 0)
  [ "$N" = "1" ] || { echo "FAIL: $K not written. Rolling back."; rollback; exit 1; }
done

If your Hermes build has no config set subcommand, use the safe sed pattern with the | delimiter — API URLs contain / and vault paths may contain spaces:

ssh "$VPS_USER@$VPS_IP" "
  for KV in 'OBSIDIAN_PATH=$OBSIDIAN_PATH' …; do
    K=\${KV%%=*}
    grep -q \"^\$K=\" ~/.hermes/.env || printf '%s\n' \"\$K=\" >> ~/.hermes/.env
    sed -i \"s|^\$K=.*|\$KV|\" ~/.hermes/.env
  done
  chmod 600 ~/.hermes/.env
"

---

Step 6 — path-specific setup

Path A — provision vault dir + sync

if [ "$OBSIDIAN_PATH" = "A" ]; then
  ssh "$VPS_USER@$VPS_IP" "mkdir -p '$OBSIDIAN_VAULT_DIR' && chmod 700 '$OBSIDIAN_VAULT_DIR'"
  if [ "$OBSIDIAN_SYNC_MODE" = "git" ]; then
    ssh "$VPS_USER@$VPS_IP" "
      cd '$OBSIDIAN_VAULT_DIR'
      if [ ! -d .git ]; then
        git clone '$OBSIDIAN_GIT_REMOTE' .
      else
        git fetch --all --prune && git pull --ff-only
      fi
      # nightly auto-pull + auto-commit + auto-push
      cat > /usr/local/bin/obsidian-vault-sync <<'SH'
#!/usr/bin/env bash
set -euo pipefail
cd '$OBSIDIAN_VAULT_DIR'
git fetch --all --prune
git pull --ff-only || true
if [ -n \"\$(git status --porcelain)\" ]; then
  git add -A
  git -c user.name='hermes-agent' -c user.email='[e-mail]' commit -m \"hermes sync \$(date -u +%FT%TZ)\"
  git push
fi
SH
      chmod +x /usr/local/bin/obsidian-vault-sync
      # cron @ 15-min cadence
      (crontab -l 2>/dev/null | grep -v obsidian-vault-sync; echo '*/15 * * * * /usr/local/bin/obsidian-vault-sync >> /var/log/obsidian-vault-sync.log 2>&1') | crontab -
    "
    echo "OK: git sync wired at 15-min cadence."
  fi
  ssh "$VPS_USER@$VPS_IP" "mkdir -p /opt/data && cat > /opt/data/obsidian-vault.md" <<DOC
# Obsidian vault filesystem contract

**Path A — vault-as-files.** The agent works with the vault as a plain directory.

- **Vault root:** \`$OBSIDIAN_VAULT_DIR\`
- **Sync mode:** \`$OBSIDIAN_SYNC_MODE\`
- **File layout:** standard Obsidian — one \`.md\` per note, folders map to Obsidian folders,
  \`.obsidian/\` holds config, attachments in \`attachments/\` (or wherever the user configured).
- **Frontmatter:** YAML block at file top for tags/aliases/dates. Preserve it on edits.
- **Wikilinks:** \`[[Note Title]]\` — resolve by scanning \`.md\` filenames case-insensitively.
- **Never touch:** \`.obsidian/workspace*.json\` (per-device UI state, causes sync conflicts).
$( [ "$OBSIDIAN_SYNC_MODE" = "git" ] && echo "- **Auto-sync:** /usr/local/bin/obsidian-vault-sync runs every 15 min via cron." )
DOC
fi

Path B — document the REST surface

if [ "$OBSIDIAN_PATH" = "B" ]; then
  ssh "$VPS_USER@$VPS_IP" "mkdir -p /opt/data && cat > /opt/data/obsidian-rest.md" <<'DOC'
# Obsidian Local REST API surface (wired via Hermes generic HTTP tool)

**Base URL:** ${OBSIDIAN_API_URL} (tunneled to the user's laptop; requires desktop app running)
**Auth:** `Authorization: Bearer ${OBSIDIAN_API_KEY}`
**TLS:** ${OBSIDIAN_TLS_MODE} — with `insecure`, curl needs `-k` (self-signed cert).

## Read

- `GET /vault/` — list all files/folders in the vault (recursive).
- `GET /vault/{path}` — read a note. `Accept: application/vnd.olrapi.note+json` returns parsed frontmatter + content.
- `GET /active/` — the currently focused note in the desktop app.
- `GET /periodic/{daily|weekly|monthly}/` — periodic notes (if the Periodic Notes plugin is on).
- `POST /search/simple/` — body: `{"query":"..."}` — filename + content search.

## Write

- `POST /vault/{path}` — create a note (fails if exists).
- `PUT /vault/{path}` — create or overwrite.
- `PATCH /vault/{path}` — insert content at heading/block. Headers:
  `Operation: append|prepend|replace`, `Target-Type: heading|block|frontmatter`, `Target: <heading name>`.
- `DELETE /vault/{path}` — remove a note.

## Common failure modes to surface in agent replies

| Code | Meaning | Fix |
|------|---------|-----|
| 000  | No response | Desktop app is closed OR tunnel is down. |
| 401  | Bearer rejected | Rotate API key in plugin settings; env may be stale. |
| 404  | Path missing | List `/vault/` to find the actual filename (case-sensitive). |
| 405  | Method not allowed | Some endpoints are GET-only (e.g. `/active/`); use `PATCH` for edits. |
| 500  | Plugin exception | Check the desktop app's dev console; often malformed markdown. |
DOC
  ssh "$VPS_USER@$VPS_IP" "chmod 644 /opt/data/obsidian-rest.md"
fi

Path C — register the mcp-obsidian stdio MCP

if [ "$OBSIDIAN_PATH" = "C" ]; then
  # Warm uvx cache
  ssh "$VPS_USER@$VPS_IP" "
    AGENT=\$(docker ps --filter name=hermes --format '{{.Names}}' | head -1)
    if [ -n \"\$AGENT\" ]; then
      docker exec \"\$AGENT\" sh -c 'uvx mcp-obsidian --help' >/dev/null 2>&1 || true
    else
      uvx mcp-obsidian --help >/dev/null 2>&1 || true
    fi
  "
  ssh "$VPS_USER@$VPS_IP" "
    hermes mcp add obsidian \
      --command uvx \
      --args 'mcp-obsidian' \
      --env 'OBSIDIAN_API_KEY=\${OBSIDIAN_API_KEY}' \
      --env 'OBSIDIAN_HOST=\${OBSIDIAN_API_URL}'
  "
fi

---

Step 7 — reload the gateway (stop + run, NOT restart)

ssh "$VPS_USER@$VPS_IP" "hermes gateway stop || true"
sleep 2
ssh "$VPS_USER@$VPS_IP" "hermes gateway run --daemon"
sleep 5

---

Step 8 — verify env is loaded inside the gateway

LOADED=$(ssh "$VPS_USER@$VPS_IP" '
  AGENT=$(docker ps --filter name=hermes --format "{{.Names}}" | head -1)
  if [ -n "$AGENT" ]; then
    docker exec "$AGENT" env | grep -c "^OBSIDIAN_"
  else
    hermes gateway env 2>/dev/null | grep -c "^OBSIDIAN_"
  fi
')
[ "$LOADED" -ge 2 ] || { echo "FAIL: expected >=2 OBSIDIAN_* vars in gateway env, saw $LOADED. Rolling back."; rollback; exit 1; }

---

Step 9 — live smoke test (path-specific)

case "$OBSIDIAN_PATH" in
  A)
    STAMP=$(ssh "$VPS_USER@$VPS_IP" 'date -u +%FT%TZ')
    ssh "$VPS_USER@$VPS_IP" "printf 'hermes wire test %s\n' '$STAMP' > '$OBSIDIAN_VAULT_DIR/.hermes-wire-test.md'"
    OK=$(ssh "$VPS_USER@$VPS_IP" "[ -f '$OBSIDIAN_VAULT_DIR/.hermes-wire-test.md' ] && echo ok || echo fail")
    [ "$OK" = "ok" ] || { echo "FAIL: could not write test note. Rolling back."; rollback; exit 1; }
    ssh "$VPS_USER@$VPS_IP" "rm '$OBSIDIAN_VAULT_DIR/.hermes-wire-test.md'"
    echo "OK: Path A vault write succeeded."
    ;;
  B|C)
    HTTP=$(ssh "$VPS_USER@$VPS_IP" '
      set -a; . ~/.hermes/.env; set +a
      TLS_FLAG=$([ "$OBSIDIAN_TLS_MODE" = "insecure" ] && echo "-k" || echo "")
      curl -sS $TLS_FLAG -o /dev/null -w "%{http_code}" \
        -H "Authorization: Bearer $OBSIDIAN_API_KEY" "$OBSIDIAN_API_URL/vault/"
    ')
    case "$HTTP" in
      200) echo "OK: Hermes-side GET /vault/ returned 200." ;;
      401) echo "FAIL: 401 from inside Hermes — env not loaded or key rotated."; rollback; exit 1 ;;
      000) echo "FAIL: tunnel down or desktop app closed."; rollback; exit 1 ;;
      *)   echo "WARN: unexpected HTTP $HTTP. Investigate manually." ;;
    esac
    ;;
esac

---

Sync-mode selection guide (Path A)

Path A operates on files in $OBSIDIAN_VAULT_DIR. The sync tool determines who is the writer of record. Pick per your usage:

git — single writer, agent-primary, laptop-secondary. Best when the agent writes far more often than the human. Every 15 minutes, the cron pulls (accepting laptop changes if any), then commits + pushes. If both sides edited the same file since the last cron, you get a merge conflict and the cron stops until a human resolves. Add a Discord/Telegram alert on non-zero exit from /usr/local/bin/obsidian-vault-sync so you notice.

syncthing — genuine multi-writer. Best when the laptop and the agent both write frequently. Syncthing detects per-file conflicts and creates .sync-conflict-YYYYMMDD-HHMMSS.md sibling files rather than merging. The agent should treat any file matching *.sync-conflict-* as read-only and surface it to the user for reconciliation.

rclone — one-way agent → cloud. Best when the agent produces knowledge (research summaries, meeting notes, research capsules) and the user consumes it via Obsidian Sync / iCloud / Dropbox. Run every 5-10 minutes via cron. Two-way rclone with sync is technically possible but the mtime-based comparison is fragile — prefer syncthing for two-way.

manual — for testing, staging, and one-shot loads. No cron installed. The agent writes; the human runs git pull or rsync when they want to see updates. Sensible while onboarding, not for production.

Sync-mode ↔ Obsidian Sync interaction

The paid Obsidian Sync product runs on the desktop app, not on the VPS. If the user has Obsidian Sync enabled AND you configure Path A + git, two different sync systems fight over the vault. Rules:

• Obsidian Sync alone — Path A + manual sync mode, and the agent uses the vault via a laptop-mounted network share. Slow and fragile; not recommended.
• hstack sync alone — Path A + git/syncthing/rclone, and Obsidian Sync stays off. Recommended.
• Both — do not. Data loss is a matter of when, not if.

---

Rate limits, reachability, and the desktop-app dependency

Path A — vault as files

No rate limits. Constraints:

• Disk I/O on the VPS. A busy agent writing every message to a note file can produce 100+ MB of .md per week. du -sh $OBSIDIAN_VAULT_DIR weekly; archive older-than-90-days notes into a subfolder if size becomes a concern.
• Git repo size (git mode). A cron committing 100 files/day into a private GitHub repo works for years, but GitHub's soft cap is 5 GB. Rotate the repo annually by squashing old history: git checkout --orphan clean main; git commit -m 'squash pre-2027'; git push --force.
• Wikilink case-sensitivity. Obsidian resolves [[Foo]] → Foo.md case-insensitively; a case-insensitive filesystem (macOS default, exFAT) hides the difference. On the Linux VPS (ext4, case-sensitive) two notes differing only in case can coexist and both be broken from Obsidian's POV.

Path B — Local REST API over tunnel

Rate-limited only by the desktop app's local capacity. Real constraints:

Constraint	Value	Symptom
Desktop app must be running	mandatory	HTTP 000 (connection refused)
Tailscale/Cloudflare tunnel must be up	mandatory	HTTP 000 or DNS resolution failure
Plugin update breaks stdio API	plugin author's discretion	500 with an obscure body; check plugin version
Laptop sleep → tunnel timeout	30 sec typical	000 for one call, then reconnect
macOS App Nap	when Obsidian minimized > 15 min	Sluggish responses; enable "Prevent App Nap" in Activity Monitor
Windows/Linux screen lock	usually irrelevant	works

Availability estimate for Path B: ~85% uptime for a normal knowledge-worker laptop (asleep at night, closed on weekends). Do not use for time-critical agent workflows. Fine for "when you get a chance, summarize today's messages into daily note."

Path C — mcp-obsidian stdio wrapper

Reachability identical to Path B (wraps the same REST API). Added constraints:

• uvx needs Python 3.11+ inside the Hermes container. Verify with docker exec <container> python3 --version.
• First-call cold start after uvx mcp-obsidian fetches the package — 3-15 seconds. Warm the cache in Step 6 (this skill does).
• Plugin version churn — the wrapper is maintained by MarkusPfundstein and pinned in VERSIONS.txt. Bumping requires reading their changelog for breaking changes.

---

Worked debugging scenarios

Scenario A — "Path B smoke test returns 000 (no response)"

Possible causes, in likelihood order:

1. Desktop app is closed. Ask the user. Fix: reopen Obsidian on the laptop.
2. Tailscale/Cloudflare Tunnel is down. From the VPS: curl -k -sSD - -o /dev/null $OBSIDIAN_API_URL/ 2>&1 | head. DNS-fail or connection-refused → tunnel is the problem. Restart the tunnel client on the laptop.
3. Laptop is asleep / hibernating. The tunnel client goes with the OS. Wake the laptop, wait 30 seconds for the tunnel to re-establish.
4. Firewall on the laptop. Newly-installed corporate MDM sometimes blocks 127.0.0.1:27124. Test locally on the laptop first: curl -k https://127.0.0.1:27124/.
5. Plugin disabled after update. Obsidian sometimes disables plugins on version bump. UI → Settings → Community plugins → confirm "Local REST API" is on.

Scenario B — "Path A cron is silently not syncing"

Symptoms: laptop-side changes don't appear on VPS, or vice versa.

Debug:

ssh "$VPS_USER@$VPS_IP" 'tail -50 /var/log/obsidian-vault-sync.log'

Common findings:

• fatal: Authentication failed — deploy key expired or was rotated. Regenerate in GitHub Settings → Deploy keys.
• error: Your local changes to the following files would be overwritten by merge — a laptop write conflicts with an unpushed agent write. The cron stops. Fix: SSH in, cd to vault, git status, resolve manually.
• CONFLICT (content): — merge conflicts from concurrent edits. Resolve, commit, push. Consider migrating to Syncthing if this happens weekly.
• Empty log for many days — cron didn't run. Check crontab -l for the entry; check journalctl -u cron for errors.

Scenario C — "Frontmatter got mangled after a PATCH"

Symptom: after an agent-side edit, YAML frontmatter no longer parses in Obsidian. Common cause: PATCH /vault/{path} with Target-Type: heading on a file where the first heading is inside the frontmatter block.

Fix at the agent side:

• Use Target-Type: frontmatter for frontmatter edits.
• Use Target-Type: heading only for ##-level and below.
• Before PATCH, GET the note with Accept: application/vnd.olrapi.note+json to read parsed frontmatter separately.

Scenario D — "Wikilinks broken on laptop but working on VPS"

Case-sensitivity mismatch: the VPS ext4 filesystem is case-sensitive; the laptop APFS/NTFS is case-insensitive. If the agent created Note.md and the user has an existing note.md in a synced folder, one silently overwrites the other on the laptop. Both exist on the VPS.

Prevention:

• Normalize new note filenames to lowercase at agent side.
• Weekly check on the VPS: find $OBSIDIAN_VAULT_DIR -type f -name '*.md' | tr '[:upper:]' '[:lower:]' | sort | uniq -d — output is filenames that only differ in case.

---

Credential + access rotation procedure

Path B/C OBSIDIAN_API_KEY rotation:

1. Desktop app → Settings → Community plugins → Local REST API → Regenerate API Key.
2. On the VPS: hermes config set OBSIDIAN_API_KEY '<new>'.
3. hermes gateway stop && sleep 2 && hermes gateway run --daemon.
4. Re-run Step 9's smoke test.
5. No separate revoke — regeneration invalidates the old key.

Path A + git deploy-key rotation:

1. GitHub → your vault repo → Settings → Deploy keys → Delete the old key.
2. On the VPS: ssh-keygen -t ed25519 -f ~/.ssh/vault_deploy -N "" -C "vault-deploy $(date -u +%F)".
3. Add the new pubkey (~/.ssh/vault_deploy.pub) as a deploy key on GitHub with write access.
4. Add a Host entry to ~/.ssh/config for the vault repo so git uses the new key:

   Host github-vault
       HostName github.com
       User git
       IdentityFile ~/.ssh/vault_deploy
   

5. Update the remote URL: cd $OBSIDIAN_VAULT_DIR && git remote set-url origin git@github-vault:<user>/<repo>.git.
6. Test: git fetch --all. Cron will pick it up next run.

Tunnel token rotation (Tailscale auth key / Cloudflare Tunnel token):

Provider-specific. In both cases, generate the new token, apply on the laptop first, verify tunnel is up with the new token, then update if the VPS uses the same tunnel for outbound (Path A + syncthing sometimes does).

---

Rollback (auto-runs on any failure above)

rollback() {
  ssh "$VPS_USER@$VPS_IP" "
    for K in OBSIDIAN_PATH OBSIDIAN_VAULT_DIR OBSIDIAN_SYNC_MODE OBSIDIAN_GIT_REMOTE OBSIDIAN_API_URL OBSIDIAN_API_KEY OBSIDIAN_TLS_MODE; do
      hermes config unset \$K 2>/dev/null || sed -i \"/^\$K=/d\" ~/.hermes/.env
    done
    hermes mcp remove obsidian 2>/dev/null || true
    rm -f /opt/data/obsidian-rest.md /opt/data/obsidian-vault.md
    (crontab -l 2>/dev/null | grep -v obsidian-vault-sync) | crontab - 2>/dev/null || true
    rm -f /usr/local/bin/obsidian-vault-sync
    hermes gateway stop; sleep 2; hermes gateway run --daemon
  "
  echo "Rolled back. Obsidian is no longer wired. (Vault dir left in place — remove manually if desired.)"
}

The rollback does not delete $OBSIDIAN_VAULT_DIR — the vault is user data, potentially syncing to their laptop. Removal is manual.

---

Pitfalls

#	Pitfall	Why it bites	Prevention
1	Assuming Obsidian has a hosted API	It doesn't. It's a desktop app; all "APIs" are community plugins running on the user's laptop.	Default to Path A for headless VPS agents.
2	Path B without a tunnel	localhost:27124 on a laptop is unreachable from the VPS.	Require Tailscale / Cloudflare Tunnel / SSH reverse-tunnel URL.
3	Path B while desktop app is closed	Plugin dies with the app; agent gets connection refused.	Detect 000 in smoke test; tell the user to keep the app open (or switch to Path A).
4	Self-signed cert breaks curl	Default plugin cert isn't trusted → HTTPS fails without -k.	Store OBSIDIAN_TLS_MODE=insecure and always pass -k unless the user installed the plugin's CA.
5	Writing to .obsidian/workspace*.json	Per-device UI state; corrupts sync.	Never PATCH under .obsidian/; document as excluded.
6	Git sync + Obsidian Sync at the same time	Two writers race, produce merge conflicts.	Pick one sync mode; Path A's cron pull-then-push assumes exclusive write.
7	Git remote unreachable from VPS	HTTPS-only clone using a token stored somewhere fragile; or SSH key not registered as deploy key.	Pre-flight git ls-remote in Step 3; require deploy-key setup.
8	Attachments path assumptions	Users configure attachments in a custom folder; hardcoding attachments/ breaks image inserts.	Read the vault's .obsidian/app.json attachmentFolderPath.
9	Wikilinks case-sensitivity	Obsidian resolves case-insensitively; naive filesystem lookups don't.	Case-fold when resolving [[Foo]] → Foo.md vs foo.md.
10	Frontmatter mangling	PATCH-append inside frontmatter block yields invalid YAML.	Use Target-Type: frontmatter on Path B, or parse-then-write on Path A.
11	gateway restart for env changes	Restart doesn't reliably re-read .env.	Always stop + run.
12	Storing API key in config.yaml	World-readable; can't rotate without restart.	Only ~/.hermes/.env, chmod 600.
13	sed with / delimiter	API URLs contain /, vault paths may contain /.	Always | delimiter.
14	Container vs host confusion (Path A)	Vault dir mounted on host, invisible to Hermes in container.	Bind-mount $OBSIDIAN_VAULT_DIR into the container; verify via Step 8 env check.
15	uvx cold start (Path C)	First MCP call after boot hangs while uv fetches mcp-obsidian.	Warm the cache once in Step 6.
16	Committing .env to the vault repo (Path A)	If .hermes/.env lives inside the vault dir by accident, the vault repo leaks secrets.	Keep .hermes outside $OBSIDIAN_VAULT_DIR; add .env to vault's .gitignore defensively.

---

Definition of done

• SSH to $VPS_USER@$VPS_IP confirmed working
• Hermes version verified on the VPS (0.15.x / 0.17.x)
• Idempotency check passed (or FORCE=1 overrode)
• WRITES_ACKNOWLEDGED=1 consent gate passed
• Path picked (A / B / C) and validated per its checklist
• Path A: git ls-remote succeeded from VPS OR non-git sync tool documented
• Path B/C: live GET on $OBSIDIAN_API_URL/ returned 200 with the bearer token
• Dry-run shown; user approved (or AUTO_APPROVE=1)
• Path-specific env vars in ~/.hermes/.env, chmod 600, not in config.yaml or chat
• Path A: vault dir provisioned; obsidian-vault-sync cron installed if git mode
• Path A: /opt/data/obsidian-vault.md filesystem contract written
• Path B: /opt/data/obsidian-rest.md REST surface written
• Path C: hermes mcp add obsidian registered; uvx cache warmed
• Gateway reloaded with stop + run (NOT restart)
• Env verified: ≥2 OBSIDIAN_* vars visible inside gateway
• Smoke test passed: vault write (A) or GET /vault/ = 200 (B/C)
• Rollback function defined and proven (re-run with FORCE=1 rewires cleanly)

See reference/TROUBLESHOOTING.md for gateway and MCP failure modes.