.env.example

# Secrets file for the AWS/SST reference deployment (DEPLOY.md) — read by
# local `npm run deploy` runs. CI generates the instance .env itself from
# deploy.yml, and the local/remote quickstarts use deploy/local/.env.example
# or deploy/remote/.env.example instead.
#
# Lives at ~/.config/vault-cortex/.env (NOT in the repo).
# Copy this template there and fill in values:
#   mkdir -p ~/.config/vault-cortex
#   cp .env.example ~/.config/vault-cortex/.env
#   chmod 600 ~/.config/vault-cortex/.env
#
# MCP bearer token — used by the Express OAuth provider for:
# 1. Static bearer token auth (backward compat with CLI tools)
# 2. Consent page password (user enters this to approve OAuth clients)
# Generate: openssl rand -hex 32
MCP_AUTH_TOKEN=

# Public URL — the HTTPS URL that MCP clients use to reach this server.
# Used as the OAuth issuer URL in discovery metadata and stamped on every
# access token; the Lambda authorizer checks tokens against the same value.
# Usually your API Gateway URL (from `npm run deploy` outputs), or your
# custom domain if you've configured one (CUSTOM_DOMAIN below). Leave it
# empty and the deploy derives it — CI (when the PUBLIC_URL repo secret is
# unset) and `npm run lightsail:up` both use https://<CUSTOM_DOMAIN> when
# the custom domain is set, else the gateway URL. Set a value only to pin
# a different hostname.
PUBLIC_URL=

# Obsidian Sync credentials
# Generate OBSIDIAN_AUTH_TOKEN once with:
#   docker run --rm -it --entrypoint get-sync-token \
#     ghcr.io/aliasunder/vault-cortex:remote
OBSIDIAN_AUTH_TOKEN=
VAULT_NAME=
# Only if your vault has end-to-end encryption enabled.
# VAULT_PASSWORD=
# Only if your GHCR package is private (instance pull login).
# GHCR_TOKEN=

# Lightsail SSH — used by `npm run lightsail:up` for SCP/SSH.
# Defaults to ~/.ssh/vault-cortex (the dedicated deploy key).
# Both local dev and CI use the same key to avoid instance replacement.
# Generate once: ssh-keygen -t ed25519 -f ~/.ssh/vault-cortex -C vault-cortex-deploy
# LIGHTSAIL_SSH_KEY=~/.ssh/vault-cortex

# SSH host — override the SSH target for Tailscale or custom DNS.
# Use the MagicDNS hostname or Tailscale IP instead of the public IP.
# LIGHTSAIL_SSH_HOST=vault-cortex

# Docker
GHCR_USER=
# Image tag the Lightsail compose pulls (default: remote — the target that
# bundles Obsidian Sync). Pin to a versioned tag (e.g. v0.27.0-remote) to
# hold a release.
# VAULT_CORTEX_TAG=remote
# Container user/group IDs (default: 1000/1000).
# PUID=1000
# PGID=1000
# Name this server registers as in Obsidian Sync (default: vault-cortex-lightsail).
# DEVICE_NAME=vault-cortex-lightsail
# Obsidian Sync conflict strategy (default: merge).
# CONFLICT_STRATEGY=merge
# Obsidian Sync direction: bidirectional | pull-only | mirror-remote (default: bidirectional).
# An invalid value stops the container at boot.
# SYNC_MODE=bidirectional
# Folders to leave out of sync, comma-separated (default: none excluded).
# SYNC_EXCLUDED_FOLDERS=
# Attachment types to sync, comma-separated: image | audio | video | pdf | unsupported (default: image,audio,video,pdf).
# To read CSV, JSON, TXT, XML, LOG, and YAML, set image,audio,video,pdf,unsupported (the value replaces the
# default list) and turn on "Sync all other types" on the uploading device.
# SYNC_FILE_TYPES=
# Obsidian settings categories to sync into the server's .obsidian/ folder
# (default: the two the server reads — daily notes settings and community
# plugin settings such as the Tasks plugin's format; "none" disables).
# A category only syncs after your desktop pushes it: Settings → Sync →
# "Vault configuration sync". Some community plugins keep API keys in their
# settings — server tools never read .obsidian/, but synced settings do
# live on the server volume. Values: app, appearance, appearance-data,
# hotkey, core-plugin, core-plugin-data, community-plugin,
# community-plugin-data — comma-separated.
# SYNC_CONFIGS=core-plugin-data,community-plugin-data
# Log verbosity: debug | info | warn | error (default: info).
# LOG_LEVEL=info
# Directory for persistent log files inside the container (default: /data/logs;
# "none" disables log files).
# LOG_DIR=/data/logs
# Days to retain persistent log files before cleanup (default: 90).
# LOG_RETENTION_DAYS=90
# IANA timezone for daily note dates and timestamps (default: UTC).
# TZ=UTC

# AWS region — only used by SST deploys (sst.config.ts) and lightsail:up's AWS lookups. Ignored by Docker containers.
# AWS_REGION=us-east-1

# ORIGIN_URL — Optional. When set, API Gateway routes through this URL
# instead of directly to the Lightsail IP on port 8000. Use with a
# Cloudflare Tunnel, Caddy reverse proxy, or any HTTPS frontend.
# Example: https://tunnel.yourdomain.dev
# Default (unset): http://<lightsail-ip>:8000
# ORIGIN_URL=

# MCP_PORT_CIDRS — Controls port 8000 on the Lightsail firewall.
# "none" = non-routable CIDR (blocks all public access, use with ORIGIN_URL)
# Comma-separated CIDRs = restrict to specific IPs
# Default (unset): 0.0.0.0/0 (open to all)
# MCP_PORT_CIDRS=none

# ORIGIN_ACCESS_SERVICE_TOKEN_ENABLED — Optional. When true, API Gateway
# sends a Cloudflare Access service token (the OriginAccessClientId and
# OriginAccessClientSecret SST secrets) to the ORIGIN_URL host on every
# request, so an Access policy on that host can admit the gateway alone.
# Requires ORIGIN_URL. DEPLOY.md "Port 8000 Hardening" has the setup steps.
# Only used by SST deploys.
# Default (unset): false
# ORIGIN_ACCESS_SERVICE_TOKEN_ENABLED=true

# These two settings choose the client IP used for OAuth rate limiting and
# request logs. API Gateway reports the visitor only in the RFC 7239
# Forwarded header (https://www.rfc-editor.org/rfc/rfc7239) and sends no
# X-Forwarded-For, so TRUST_FORWARDED_HOPS is the setting that finds the
# visitor; TRUST_PROXY_HOPS only sets how many X-Forwarded-For hops feed the
# fallback client IP, used when the Forwarded header is ignored or absent.
# The defaults shown below match the "API Gateway (default)" row.
#
#   What sits in front of the instance     TRUST_PROXY_HOPS  TRUST_FORWARDED_HOPS  Client IP is
#   API Gateway (default)                  1                 1                     the visitor
#   Gateway → tunnel (ORIGIN_URL) that     2                 0                     the gateway's address
#     admits any client
#   Gateway → tunnel that admits only      2                 1                     the visitor
#     the gateway
#   Gateway → a tunnel/proxy that cannot   2                 0                     the gateway's address
#     check headers
#   CDN → gateway's custom domain, and     2                 2                     the visitor
#     the CDN is the only way in
#     (DISABLE_EXECUTE_API_ENDPOINT=true)
#
# On the rows where the client IP is the visitor, it comes from the Forwarded
# header and TRUST_PROXY_HOPS is not consulted. On the TRUST_FORWARDED_HOPS=0
# rows, the Forwarded header is ignored and the client IP is whatever
# TRUST_PROXY_HOPS resolves from X-Forwarded-For — the gateway's own address,
# never the visitor, since the gateway sends no X-Forwarded-For.
#
# A tunnel host admits only the gateway once ORIGIN_ACCESS_SERVICE_TOKEN_ENABLED
# above is set and the Access policy is in place (DEPLOY.md "Port 8000
# Hardening", steps 5–10). Until then the host passes any client-written
# Forwarded header through, which is why the "admits any client" row sets
# TRUST_FORWARDED_HOPS to 0. With 0, every visitor shares one rate-limit
# bucket (the gateway's address), but no visitor can pick their bucket.
# TRUST_PROXY_HOPS=1
# TRUST_FORWARDED_HOPS=1

# CUSTOM_DOMAIN — Optional. Custom domain for API Gateway, replacing the
# auto-generated execute-api URL for clients.
# - Read by `npm run deploy` (provisions the gateway domain) and by
#   `npm run lightsail:up` (derives the matching PUBLIC_URL).
# - Using one from a laptop deploy: uncomment both lines below so the
#   two commands see the same value. CI deploys set both as repo
#   secrets instead.
# - Requires CUSTOM_DOMAIN_CERT_ARN: an ISSUED ACM cert in the API's
#   region, covering the domain.
# - DNS stays with your provider — after deploy, point a CNAME at the
#   gateway's target hostname (DEPLOY.md § Custom Domain has the aws
#   CLI command to fetch it).
# CUSTOM_DOMAIN=mcp.example.com
# CUSTOM_DOMAIN_CERT_ARN=arn:aws:acm:us-east-1:<account>:certificate/<id>

# DISABLE_EXECUTE_API_ENDPOINT — Optional. When true, API Gateway stops
# answering on its default execute-api hostname, so the custom domain is
# the only way in. Requires CUSTOM_DOMAIN. Set it once every client uses
# the custom domain; clients still on the default URL lose access at the
# next deploy. If a CDN sits in front of the custom domain, set this
# before TRUST_FORWARDED_HOPS=2. Only used by SST deploys.
# Default (unset): false
# DISABLE_EXECUTE_API_ENDPOINT=true

# vault-cortex configuration
# Enable or disable the embedding pipeline (default: true).
# When true, notes are chunked and embedded via a local ONNX model
# (bge-small-en-v1.5) for hybrid search — FTS5 keyword + vector semantic
# similarity fused via RRF. First startup is slow (~5min for 700 notes);
# subsequent starts are fast via content-hash caching.
# Set to false to disable model download and use FTS5 search only.
# EMBEDDING_ENABLED=true
# Reranking mode for hybrid search results (default: blended).
# "blended" uses a cross-encoder to refine result ordering with
# position-aware score blending (~200ms added latency).
# "none" skips reranking for lower latency.
# Only takes effect when EMBEDDING_ENABLED=true.
# RERANK_MODE=blended
# Windows bind-mount mode (default: false).
# Set to true when your vault is on a Windows drive (Docker Desktop).
# Enables polling for the file watcher and rename-based moves across
# the Docker Desktop/WSL2 bridge.
# WINDOWS_MODE=false
#
# Largest file vault_read_file will read, in bytes (default: 52428800 = 50 MiB).
# MAX_FILE_BYTES=52428800
# Byte budget for images returned by vault_read_file, in binary bytes before
# base64 encoding (default: 49152 = 48 KiB, sized for Claude Code's response cap).
# MAX_IMAGE_OUTPUT_BYTES=49152
# Max PDF pages to render as images for raw: true (default: 5).
# MAX_PDF_RENDER_PAGES=5
# Enable or disable the memory layer (default: true).
# Set to false to hide memory tools, skip auto-initialization, and omit
# memory references from server metadata. MEMORY_DIR still supplies the
# defaults for PROTECTED_PATHS and ORPHAN_EXCLUDE_FOLDERS when false.
# MEMORY_ENABLED=true
# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
# Set to false to hide file tools entirely. Useful for remote deployments where
# Obsidian Sync has attachment syncing disabled (no files on disk).
# FILE_TOOLS_ENABLED=true
# Run the server in read-only mode (default: false).
# Set to true to hide every vault-writing tool; the memory folder is not
# auto-created and server metadata omits write references.
# READONLY_MODE=false
# Hide individual tools by name, comma-separated (default: none hidden).
# Names match the README tools table: https://github.com/aliasunder/vault-cortex#tools
# Subtractive only — cannot re-enable a tool another setting hides; an
# unknown tool name stops the server at startup.
# DISABLED_TOOLS=vault_delete_note,vault_move_note
# Memory folder name in your vault (default: "About Me")
# MEMORY_DIR=About Me
# Daily notes folder and filename format (default: read from the
# vault's .obsidian/daily-notes.json, synced to the server via SYNC_CONFIGS
# above; falls back to "Daily Notes" and YYYY-MM-DD). Folder is any
# vault-relative path (Journal, Planner/Daily); format takes the same tokens
# as Obsidian's date format setting.
# DAILY_NOTES_FOLDER=Journal
# DAILY_NOTES_FORMAT=YYYY-MM-DD
# Comma-separated folders protected from deletion and moves. Default: MEMORY_DIR plus
# the daily notes folder, read from DAILY_NOTES_FOLDER or .obsidian/daily-notes.json
# (default "Daily Notes"). When set, replaces the whole default — include the
# daily notes folder in your list if needed.
# PROTECTED_PATHS=About Me,Daily Notes
# Comma-separated folders excluded from orphan detection.
# Default: the daily notes folder, Templates, and MEMORY_DIR.
# DAILY_NOTES_FOLDER wins; otherwise .obsidian/daily-notes.json is reread
# on each query, falling back to "Daily Notes". Root-level daily notes remain eligible.
# When set, replaces the whole default — include every folder to keep excluded.
# Set ORPHAN_EXCLUDE_FOLDERS=, to exclude nothing; an empty value uses the defaults.
# Apply env changes by redeploying; synced Obsidian settings apply on the next query.
# ORPHAN_EXCLUDE_FOLDERS=Daily Notes,Templates,About Me
# URL shown in OAuth discovery metadata (default: https://github.com/aliasunder/vault-cortex)
# SERVICE_DOCUMENTATION_URL=https://github.com/youruser/your-fork