Getting Started

Relevant source files

• ARCHITECTURE.md
• DOCKERHUB.md
• README.md
• assets/social-preview.png
• assets/social-preview.svg
• cli/README.md
• cli/package.json
• deploy/local/.env.example
• deploy/local/README.md
• deploy/local/docker-compose.yml
• deploy/remote/README.md
• docker-compose.local.yml
• llms-install.md
• package-lock.json
• package.json
• server.json
• templates/memory/README.md

Vault Cortex provides a flexible deployment model designed to move from a local setup to a fully remote, synchronized vault. The server operates directly on .md files using a Docker-based architecture, eliminating the need for an active Obsidian desktop instance or third-party REST API plugins [ARCHITECTURE.md:23-32].

The fastest path to a working setup is the interactive CLI:

---

Deployment Paths

There are three primary ways to deploy Vault Cortex, ranging from local development to a production-grade AWS environment. All modes run the vault-cortex Docker image, which is available in two tags: :latest (MCP server only) and :remote (MCP server + Obsidian Sync) [deploy/remote/README.md:8-11].

1. Local Docker (Simplest)

Best for users who want to use MCP tools with a vault already on their local machine. This mode uses a bind-mount to connect your local folder to the container [deploy/local/README.md:3-5].

• Setup: Run npx vault-cortex@latest init [deploy/local/README.md:18-19].
• Data Flow: The server reads and writes directly to your local filesystem via the VAULT_PATH mount point [server.json:25-38].
• Windows Support: If your vault is on a C: drive, set WINDOWS_MODE=true in .env. This enables polling for the file watcher and a rename-based write strategy to navigate the Docker Desktop/WSL2 bridge [deploy/local/README.md:192-205].

2. Remote with Obsidian Sync (Recommended)

Enables access to your vault from any device while keeping everything in sync. This deployment runs two services supervised by s6-overlay inside one container: obsidian-sync (the headless sync client) and the MCP server [deploy/remote/README.md:8-11].

• Setup: Run npx vault-cortex@latest init --mode remote on a VPS [deploy/remote/README.md:29-31].
• Prerequisites: An Obsidian Sync subscription, an OBSIDIAN_AUTH_TOKEN (generated via get-sync-token), and a PUBLIC_URL [deploy/remote/README.md:20-25].
• Security: Secured by OAuth 2.1, allowing clients like Claude Mobile to connect via a browser-based consent page [README.md:18-18].

3. AWS Reference Deployment

A production-grade architecture provisioned by sst.config.ts [ARCHITECTURE.md:38-40].

• Infrastructure: Uses AWS Lightsail for the container and API Gateway for TLS termination [ARCHITECTURE.md:74-80].
• Defense in Depth: Combines a path-aware Lambda authorizer (src/functions/authorizer.ts) with application-layer JWT/Static Token validation [ARCHITECTURE.md:57-59].

Feature	Local Docker	Remote (Sync)	AWS Reference
Image Tag	:latest	:remote	:remote
Persistence	Bind Mount	Named Docker Volume	Named Docker Volume
Sync	None	Obsidian Sync	Obsidian Sync
Auth	Static Token / OAuth	OAuth 2.1	OAuth + Lambda
Infrastructure	Local Machine	VPS / Docker	Lightsail + APIGW

Sources: [README.md:51-112], [ARCHITECTURE.md:42-60], [deploy/local/README.md:1-40], [deploy/remote/README.md:1-133], [server.json:1-165]

---

MCP Client Configuration

Vault Cortex supports the Model Context Protocol via streamable-http transport [ARCHITECTURE.md:28-28].

Claude Desktop

Claude Desktop requires https for its custom connector dialog. Local HTTP setups must use the mcp-remote bridge to map the HTTP endpoint to a stdio process [deploy/local/README.md:93-98].

File: claude_desktop_config.json

Claude Code

Claude Code supports HTTP transport natively [deploy/local/README.md:75-81].

Other Clients (Cursor, OpenCode, Cline)

1. OAuth Clients: Add the URL (e.g., http://localhost:8000/mcp). A browser window will open; enter your MCP_AUTH_TOKEN to approve [deploy/local/README.md:120-127].
2. Static Token Clients: For clients like Cline, provide the Authorization: Bearer <TOKEN> header directly in settings [server.json:49-64].

Sources: [deploy/local/README.md:65-138], [deploy/remote/README.md:164-180], [server.json:46-65]

---

System Initialization and Data Flow

The server performs a specific boot sequence to prepare the hybrid search index and memory layers.

Startup Sequence

1. Environment Validation: Loads configuration, requiring MCP_AUTH_TOKEN and VAULT_PATH (or VAULT_NAME for remote) [server.json:66-72].
2. Index Rebuild: Scans the vault to populate the SQLite FTS5 index and non_md_files table [deploy/remote/README.md:105-108].
3. Memory Bootstrap: If MEMORY_ENABLED is true, it ensures the MEMORY_DIR (default "About Me") exists [server.json:95-108].
4. Watcher Initialization: Starts the file-watcher.ts (using chokidar) to keep the index and embeddings current [ARCHITECTURE.md:86-86].

Request Flow Diagram

The following diagram bridges high-level deployment components to internal code entities.

Diagram: "MCP Request Lifecycle"

Sources: [ARCHITECTURE.md:63-121], [deploy/local/README.md:25-31], [deploy/remote/README.md:105-108], [server.json:16-48]

---

Fast-Track CLI: npx vault-cortex init

The CLI is the recommended entry point. It automates secret generation and scaffolds the environment [cli/README.md:3-16].

Key Functions performed by the CLI:

• Mode Selection: Interactive choice between local and remote [cli/README.md:43-46].
• Token Generation: Generates a secure MCP_AUTH_TOKEN [cli/README.md:54-54].
• Sync Integration: Offers to run get-sync-token during remote setup [cli/README.md:59-61].
• Container Management: Scaffolds config and starts the container, waiting for the /healthz check [cli/README.md:55-55].

Diagram: "CLI Initialization Flow"

Sources: [cli/README.md:37-75], [deploy/local/README.md:15-23], [deploy/remote/README.md:29-36], [cli/package.json:1-50]