ob is a single-process Bun server, packaged as a single Docker image, that keeps one or more Obsidian vaults bidirectionally synced via the official obsidian-headless CLI, embeds and indexes their Markdown into an in-process LanceDB store, and exposes both a REST API and a Streamable HTTP/SSE MCP server so an LLM agent can CRUD documents and search them by natural language. One container, one process, one image — no orchestration required.

The canonical invocation:

docker run --rm \
  -p 3000:3000 \
  -v ob-data:/data \
  -e OBSIDIAN_AUTH_TOKEN=... \
  -e VAULTS_JSON='[{"name":"v"}]' \
  ghcr.io/<org>/ob:<tag>

• -p 3000:3000 — REST + MCP listener.
• -v ob-data:/data — persists synced vaults, the LanceDB store, and the embedding-model cache.
• OBSIDIAN_AUTH_TOKEN — bootstrapped to ${XDG_CONFIG_HOME:-/home/ob/.config}/obsidian-headless/auth_token on first start. Mounting a token file at the same path also works.
• VAULTS_JSON — the vaults to sync; see the env-var table below.

All runtime configuration is environment-variable driven (no config files baked into the image). The architecture spec is the single source of truth; this table mirrors it for convenience.

The OB_SYNC_* family runs ob sync-config once per vault between ob sync-setup and ob sync --continuous. Unset vars omit the corresponding flag entirely (preserving whatever was on disk); empty strings forward verbatim as the upstream "empty to clear" sentinel; if every OB_SYNC_* var is unset the call is skipped. Invalid enum values fail fast with exit 78 before any vault is touched. For example, -e OB_SYNC_FILE_TYPES=image,audio,pdf,video,unsupported keeps the default attachment types AND syncs everything else (the typical fix for "my .json/.txt/.docx files are missing in the cloud").

With the default transformers embedding provider, the first request triggers a one-time download of Xenova/all-MiniLM-L6-v2 (~90 MB) into /data/models/. Subsequent starts read from the cache, so mounting /data on a persistent volume keeps that cost paid once. To pre-warm, hit any indexing or search endpoint after start; or set EMBEDDING_PROVIDER=openai to skip the local model entirely.

• GET /healthz — liveness; returns 200 once the process is up. Wired into the image's HEALTHCHECK.
• GET /readyz — readiness; returns 200 only after every configured vault has completed sync-setup and its initial index pass.
• GET /metrics — text/plain Prometheus exposition.

The image's HEALTHCHECK deliberately probes /healthz rather than /readyz so a long initial scan doesn't flap the container as unhealthy. Orchestrators that want readiness-gated traffic should configure their own probe against /readyz.

The system is fully spec-driven. Every behavior the running container exposes is described in one of these documents:

• Architecture — single-process topology, runtime, configuration, container shape, and standing testing/lint conventions every other spec inherits.
• Obsidian Sync — auth-token bootstrap and per-vault obsidian-headless child-process supervision.
• Vault Indexer — chokidar watcher, Markdown chunker, embedding providers, and per-vault LanceDB store.
• REST API — vault-scoped HTTP CRUD over arbitrary files plus natural-language search over Markdown.
• MCP Server — Streamable HTTP/SSE MCP server mirroring the REST surface as MCP tools and resources.

Change documents under docs/changes/ describe how the project got from greenfield to today.

Toolchain pins live in mise.toml (Bun + Node) and package.json (@biomejs/biome, typescript, runtime deps). obsidian-headless and the Docker base images are pinned in the Dockerfile.

mise install         # install Bun + Node 22 at the pinned versions
bun install          # resolve deps from bun.lock
bun run test:cov     # full test suite + 100% coverage gate on src/

make build (the default target) runs everything CI enforces:

make build           # lint + typecheck + tests + coverage
make test            # tests + coverage only
make image           # sudo docker build -t ob:dev .   (local sanity build)

Releases and image publishing are fully automated — there is no make image-push ceremony any more. Every PR title that lands on main is a Conventional Commit, which feeds two GitHub Actions workflows:

• Merge to main (non-docs paths) → Docker workflow publishes ghcr.io/fx/ob:main (rolling) and ghcr.io/fx/ob:sha-<short> (immutable). Docs- and Markdown-only merges are skipped by the workflow's paths-ignore, so they do not republish :main / :sha-<short>.
• Merge the release-please PR → release-please cuts a vX.Y.Z git tag; tag pushes are NOT path-filtered, so the Docker workflow always publishes ghcr.io/fx/ob:X.Y.Z, ghcr.io/fx/ob:X.Y, ghcr.io/fx/ob:X, and updates ghcr.io/fx/ob:latest.

Pinning guidance for consumers:

The Makefile targets above are still useful for local sanity builds; they are not part of the release path.

bun run lint runs Biome and hadolint Dockerfile. Hadolint is preinstalled in the dev container; on a fresh machine, install it once:

sudo curl -fsSL https://github.com/hadolint/hadolint/releases/download/v2.12.0/hadolint-Linux-x86_64 \
  -o /usr/local/bin/hadolint && sudo chmod +x /usr/local/bin/hadolint

test/docker.test.ts builds the production image and runs ob --help + id -u against it. It is gated behind DOCKER_E2E=1 so the default bun test suite skips it (no daemon required). To exercise it locally:

sudo service docker start
DOCKER_E2E=1 bun test test/docker.test.ts