Vault Cortex is configured primarily through environment variables, which are parsed and validated at startup into a structured, immutable ServerConfig object. This page details every configuration option, its impact on the system, and how these settings differ across deployment modes.
The configuration is managed by src/vault-mcp/config.ts, which uses the env-var library for type-safe environment access and zod for structural validation of folder names and URLs src/vault-mcp/config.ts3-5 At runtime, the loadConfig function processes process.env (or a provided environment record) and freezes the resulting object to prevent accidental mutation src/vault-mcp/config.ts82-181
The following diagram illustrates how environment variables are processed and distributed to the internal layers.
Configuration Data Flow
Sources: src/vault-mcp/config.ts82-181 docker-compose.yml22-60
These variables are essential for the server's basic functionality, including identity, authentication, and vault access.
| Variable | Description | Default | Requirement |
|---|---|---|---|
VAULT_PATH | Absolute path to the Obsidian vault on the host. In Docker, this is mapped to /vault docker-compose.yml36 | None | Required (Local) |
MCP_AUTH_TOKEN | Static bearer token for MCP client authentication and OAuth consent server.json68-72 | None | Required |
PUBLIC_URL | The base URL used for OAuth discovery metadata and issuer identification server.json74-77 | http://localhost:8000 | Optional |
VAULT_NAME | The exact name of the vault (case-sensitive). Required for Obsidian Sync deploy/remote/.env.example20-21 | None | Mode-dependent |
OBSIDIAN_AUTH_TOKEN | Auth token for the obsidian-sync service deploy/remote/.env.example15-18 | None | Mode-dependent |
In the Local Docker deployment, VAULT_PATH in your .env refers to the host path, which is then bind-mounted to /vault:rw inside the container deploy/local/docker-compose.yml52 The server internally uses the container-side path defined by the VAULT_PATH environment variable deploy/local/docker-compose.yml24
Vault Cortex features a hybrid search engine (FTS5 + Vector). The embedding pipeline is computationally intensive and can be opted out to save resources.
EMBEDDING_ENABLED (Boolean)true: Notes are chunked and embedded via a local ONNX model (bge-small-en-v1.5). Subsequent starts use content-hash caching to skip unchanged files server.json79-82false: No ONNX model is downloaded, no vector tables are created, and search falls back to FTS5 keyword search only server.json79-82RERANK_MODE (Enum: blended | none)blended: After Reciprocal Rank Fusion (RRF), a cross-encoder rescores top candidates using position-aware score blending. This adds ~200ms latency but improves relevance server.json84-88none: Skips the reranking pass to minimize latency. Only takes effect if EMBEDDING_ENABLED is true server.json84-88The memory layer provides agents with structured context. It can be fully disabled via MEMORY_ENABLED.
| Variable | Description | Default |
|---|---|---|
MEMORY_ENABLED | Toggle for the memory layer. When false, memory tools are hidden and bootstrap is skipped server.json95-98 | true |
MEMORY_DIR | Folder name for memory files (e.g., "About Me") server.json105-108 | About Me |
PROTECTED_PATHS | Comma-separated folders blocked from vault_delete_note server.json132-134 | MEMORY_DIR, Daily Notes |
ORPHAN_EXCLUDE_FOLDERS | Folders excluded from vault_find_orphans server.json136-138 | Daily Notes, Templates, MEMORY_DIR |
Sources: server.json95-138 src/vault-mcp/config.ts85-113
These variables prevent memory exhaustion and manage payload sizes for different MCP clients (e.g., Claude Code, Claude Desktop).
| Variable | Description | Default |
|---|---|---|
MAX_FILE_BYTES | Largest file vault_read_file will read (memory guard) server.json145-149 | 52428800 (50 MiB) |
MAX_IMAGE_OUTPUT_BYTES | Byte budget for images after downscaling/recompression server.json151-156 | 49152 (48 KiB) |
MAX_PDF_RENDER_PAGES | Max PDF pages to render as images when raw: true is used server.json157-161 | 5 |
FILE_TOOLS_ENABLED | Toggle for vault_read_file and vault_list_files server.json100-103 | true |
Sources: server.json145-161 src/vault-mcp/config.ts138-166
WINDOWS_MODE (Boolean)This flag is critical for users running the Docker container on Windows via Docker Desktop. It triggers two specific behavioral changes:
| Variable | Description | Default |
|---|---|---|
LOG_LEVEL | Verbosity: debug, info, warn, error server.json115-119 | info |
LOG_DIR | If set, writes date-stamped log files to disk server.json121-124 | Unset (Stdout) |
LOG_RETENTION_DAYS | Retention period for log files before auto-cleanup server.json126-130 | 30 |
TZ | IANA timezone for daily note resolution and memory timestamps server.json110-113 | UTC |
Sources: server.json110-130 docker-compose.yml40-43
Vault Cortex adapts its configuration requirements based on the deployment mode selected.
This diagram maps environment variables to the specific code entities and deployment logic they influence.
Configuration Mapping
| Feature | Local Docker | Remote (Obsidian Sync) | AWS Reference |
|---|---|---|---|
| Primary Storage | Bind-mount (VAULT_PATH) | Named Volume (vault_data) | Named Volume + Lightsail |
| Syncing | None | Headless Obsidian Sync | Headless Obsidian Sync |
| Auth Layer | MCP Bearer / OAuth | MCP Bearer / OAuth | Lambda Authorizer + OAuth |
| Networking | localhost:8000 | Public HTTPS / Tunnel | API Gateway HTTPS |
| Windows Support | WINDOWS_MODE=true | N/A (runs on Linux VPS) | N/A |
Sources: deploy/local/.env.example1-92 deploy/remote/.env.example1-114 .env.example1-128 DEPLOY.md39-64
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.