The Local Docker Deployment is the simplest way to run Vault Cortex. It runs as a single Docker container on your host machine and accesses your Obsidian vault directly through a filesystem bind-mount. This mode is ideal for local-only use cases where cloud synchronization or remote access is not required.
In this deployment mode, the vault-cortex container maps a local directory on the host (your vault) to the /vault path inside the container deploy/local/docker-compose.yml24 The server manages its own SQLite search index and metadata cache in a dedicated Docker volume named mcp_data deploy/local/docker-compose.yml53
The following diagram illustrates how a request from an MCP client flows through the local deployment into the code entities that manage the vault and search index.
Local Request Lifecycle
Sources: deploy/local/docker-compose.yml17-53 deploy/local/README.md67 deploy/local/docker-compose.yml25
The deployment is configured via a .env file located in the same directory as the docker-compose.yml. The npx vault-cortex@latest init command automates this setup by scaffolding the necessary files deploy/local/README.md17-23
| Variable | Description | Source |
|---|---|---|
MCP_AUTH_TOKEN | A static bearer token for client authentication. | deploy/local/.env.example8 |
VAULT_PATH | Absolute path to the vault on the host machine. | deploy/local/.env.example12 |
| Variable | Description | Default |
|---|---|---|
PORT | The host port to expose the MCP server on. | 8000 |
EMBEDDING_ENABLED | Enables local ONNX embedding pipeline for hybrid search. | true |
MEMORY_ENABLED | Whether to enable the "About Me" memory layer. | true |
WINDOWS_MODE | Activates polling watcher and rename-based writes. | false |
Sources: deploy/local/.env.example4-92 deploy/local/docker-compose.yml21-42
WINDOWS_MODE)Vault Cortex includes specialized logic for running on Windows via Docker Desktop. When WINDOWS_MODE=true is set, the server adjusts its behavior to handle limitations of the WSL2/Hyper-V filesystem bridge deploy/local/README.md192-208
inotify events often do not cross the Docker Desktop/WSL2 bridge from a Windows host. WINDOWS_MODE switches the chokidar file watcher to polling to ensure the search index and embeddings stay current deploy/local/README.md196-199 deploy/local/.env.example88-92vault_move_note (via atomicWriteFileExclusive) may be unsupported on certain Windows mount configurations. The server switches to a rename-based strategy to ensure vault-wide link rewriting and file moves work correctly deploy/local/README.md197-199Sources: deploy/local/README.md192-208 deploy/local/.env.example88-92 deploy/local/docker-compose.yml37-39
The local deployment utilizes the ghcr.io/aliasunder/vault-cortex:latest image, which is the standard MCP server image Dockerfile3-4 deploy/local/docker-compose.yml18 This image uses tini as PID 1 to ensure that SIGTERM signals are forwarded correctly, allowing SQLite WAL (Write-Ahead Logging) to close cleanly Dockerfile56-57 Dockerfile67
The docker-compose.yml defines the vault-cortex service with these characteristics:
mcp_data is mounted to /data to persist the SQLite search index (index.db) and logs across container restarts deploy/local/docker-compose.yml53 deploy/local/docker-compose.yml70-71node-based health check polls http://127.0.0.1:8000/healthz every 15 seconds, using fetch to verify server availability deploy/local/docker-compose.yml56-67rw) permissions to allow the server to perform CRUD operations and surgical patches deploy/local/docker-compose.yml52Local Component Interaction
Sources: deploy/local/docker-compose.yml17-67 deploy/local/README.md139-148 Dockerfile56-67
Claude Desktop's "Add custom connector" UI requires https. For a local http server, you must use the mcp-remote bridge in claude_desktop_config.json deploy/local/README.md93-97
Sources: deploy/local/README.md99-118
Claude Code supports direct HTTP transport. During the first connection, it will open a browser for OAuth consent deploy/local/README.md75-89
Sources: deploy/local/README.md79-81
http://localhost:8000/mcp as a remote MCP server deploy/local/README.md122MCP_AUTH_TOKEN deploy/local/README.md124-126For clients that do not support the full OAuth 2.1 flow, use a static Authorization header with the raw MCP_AUTH_TOKEN deploy/local/README.md128-132
http://localhost:8000/mcpAuthorization: Bearer <your-token>Sources: deploy/local/README.md133-137
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.