Deployment Modes

Deployment Modes

obsidian-tc runs in five modes. The companion plugin and the vault always live on the same machine as the server — only the MCP client may be remote.

Aspect	STDIO local	HTTP local	HTTP remote	Docker	Standalone binary
Process model	Subprocess of the MCP client	Background daemon	Daemon on a remote host	Container w/ bind-mount	Compiled Bun binary
Bind address	n/a	127.0.0.1 enforced	0.0.0.0 permitted	per docker run -p	per transport
Auth	none OK	none OK	JWT required (hard refusal in none on non-loopback)	per HTTP mode	per transport
Cold start	~500ms	one-time start; <50ms/req	+ tunnel latency	~1s	~100ms
Multi-client	1 per process	many	many	many	1 (STDIO) or many (HTTP)

STDIO local (default)

For Claude Desktop / Claude Code. The client launches obsidian-tc serve --stdio as a subprocess — one per client. none auth is typical; the trust boundary is the parent process.

{ "mcpServers": { "obsidian-tc": { "command": "obsidian-tc", "args": ["serve", "--stdio"] } } }

HTTP local

obsidian-tc serve --http --port 8765

One warm Bun process; many local clients connect to 127.0.0.1:8765. The native module stays warm, so cold-start savings compound for agent workloads making many short calls. none auth accepted on loopback.

HTTP remote

Server runs on a remote host (with the vault co-located); clients connect over Cloudflare Tunnel or SSH local-forward. The server refuses to bind a non-loopback host in none mode — a hardcoded check, not a config flag. JWT is mandatory. See Security and ACL.

Docker

docker run -v /path/to/vault:/vault \
  ghcr.io/the-40-thieves/obsidian-tc:1.3.3 serve --http

The native module is built into the image; the vault is bind-mounted. Obsidian (a GUI app with the companion + REST API plugins) runs on the host, not in the container, so the container must reach Obsidian's REST API port: --network host on Linux, or explicit port mapping on macOS/Windows.

Standalone binary

bun build --compile produces one executable per platform (~80 MB; runtime + native statically linked). No Bun install needed. Distributed via GitHub Releases.

Edge case: vault on a laptop, agents on a server

Topology A (recommended) — server colocated with the vault. obsidian-tc + Obsidian + REST API plugin all run on the laptop; a remote agent tunnels MCP calls to the laptop's HTTP endpoint. Server↔plugin calls stay local; only the agent↔server hop crosses the network.

Topology B — server colocated with the agent. Every plugin-bridge call tunnels back to the laptop's Obsidian, incurring RTT per op. Available but not the default.