vault-cortex (CLI)

Set up a Vault Cortex MCP server for your Obsidian vault in one command:

npx vault-cortex@latest init

Vault Cortex is a standalone, remote-capable MCP server that gives any AI agent hybrid search, task management, structured memory, and read/write access to your Obsidian vault — including its images, PDFs, canvases, and data files — see the full feature overview. The server runs as a Docker container; this CLI scaffolds the config and manages the container so you don't have to.

Commands

• init — interactive setup: scaffold the config, generate the auth token, start the server
• configure — change optional settings interactively and restart to apply them
• upgrade — pull the latest image and re-create the container; your data stays
• start — start the server with your saved settings, e.g. after down
• restart — re-create the container so your .env edits take effect; no image pull
• logs — show the server's logs, live or after the fact
• down — stop and remove the container; your data stays
• get-sync-token — generate an Obsidian Sync auth token for remote setups

Run npx vault-cortex@latest <command> --help for all flags.

init

npx vault-cortex@latest init

What it does:

1. Asks how you want to run it:
   • Local — Docker on this machine, your vault folder bind-mounted
   • Remote — a VPS with Obsidian Sync, reachable from any device
2. Offers the most common optional settings — memory layer and folder, daily notes folder and format, file tools, read-only mode, semantic search, port, timezone (plus sync direction for remote) — press enter to keep the defaults, or pick the ones you want to change
3. Generates a .env file with a securely generated MCP_AUTH_TOKEN
4. Optionally starts the container and waits for the health check
5. Prints your connection details — the MCP URL, your auth token, and how to connect your client

Remote setups: init offers to generate your Obsidian Sync token during the flow. If you skip it, init still offers to start the server, which then shows a sign-in page at your PUBLIC_URL. Set up HTTPS first: the page sends your Obsidian password to the server.

Re-running init where a setup already exists:

• Stops when the folder holds an install of the other mode (a remote install for a local setup, or the reverse), and points you to start.
• Asks before changing anything. Declining leaves everything unchanged and points you to configure, the command for changing settings in place.
• Never overwrites existing files without asking.
• Keeps the install's name, and stops if --instance-name gives a different one.
• Keeps the install's port, unless you change it with --port or in the optional settings.

Running a second vault on the same machine:

1. Start Docker, so init can check which names and ports are in use.

2. Run init again with a new --dir:

   npx vault-cortex@latest init --dir ./vault-cortex-work

3. Give the new install its own name and port when init asks. It asks when the machine already has a vault-cortex container or data volume, and suggests the first port no other container uses. The name is saved as INSTANCE_NAME in the install's .env and names its container and data.

4. Pass that --dir to every command for the install, such as upgrade or logs. Each command acts only on that install.

5. Add the install to your MCP client as its own connector.

Flags:

• --mode local|remote — skip the mode prompt
• --vault-path <path> — absolute path to your vault (local mode)
• --dir <path> — directory to write config files into (default ./vault-cortex)
• --instance-name <name> — name for this install's container and data (default vault-cortex); lowercase letters, digits, - and _. Naming an install that already exists reuses its data, so use it only for the same vault set up again
• --port <port> — host port for this install (default 8000); a port another container already publishes is refused
• --yes — non-interactive local setup with defaults; requires --vault-path, and --instance-name when the name is already in use

Non-interactive example:

npx vault-cortex@latest init --yes --vault-path /path/to/YourVault

configure

Change optional settings on an existing setup:

npx vault-cortex@latest configure

Shows the same settings chooser as init, pre-filled with your current values, saves your picks to .env, and offers to restart the container so they take effect.

Settings not in the chooser live in .env too: edit the value there, then run restart. That's also how you clear a daily notes setting back to your vault's own configuration — comment out or delete its line.

Use --dir <path> if your config isn't in ./vault-cortex.

upgrade

Pull the latest image, re-create the container, and verify health:

npx vault-cortex@latest upgrade

Run it from the same directory where you ran init — it looks for your config in ./vault-cortex/.env (pass --dir <path> if you scaffolded somewhere else).

Safe by design:

• Your vault data, search index, and .env settings are preserved across upgrades — only the server image is replaced.
• Any edits you've made to .env are applied on the way up (docker restart alone does not re-read env files).

Prefer Docker Compose? The CLI uses docker run for simplicity, but the deploy guides include Compose files you can use directly. If you set up with Compose, stick with Compose for updates too (docker compose pull && docker compose up -d) — the CLI and Compose manage the container independently.

start

Start the server with your saved settings and verify health:

npx vault-cortex@latest start

This is the command the CLI's own guidance points to whenever the server isn't running — after down, or an init where the server wasn't started. It's the same cycle as restart under the name you'd look for: the install's existing container is replaced, and Docker pulls the server image automatically on a first start. A container of another app that holds the install's name is left alone, and start stops with an error that names it.

Use --dir <path> if your config isn't in ./vault-cortex.

restart

Re-create the container from your .env and verify health:

npx vault-cortex@latest restart

Use it after editing .env — settings are only read when the container is created, so a plain docker restart won't pick them up, but this will. Unlike upgrade, it never updates the server image: you get the same version back, with your current settings applied.

Use --dir <path> if your config isn't in ./vault-cortex.

logs

Show the server's logs:

npx vault-cortex@latest logs

Flags:

• --follow — keep streaming new output until you press ctrl-C
• --since <time> — only logs newer than this (e.g. 10m, 2h, or a timestamp)
• --dir <path> — directory containing .env (default ./vault-cortex)

npx vault-cortex@latest logs --follow --since 10m

down

Stop and remove the container:

npx vault-cortex@latest down

Safe by design: your vault, search index, and .env settings all live outside the container, so nothing is lost. Start again any time with start. Running down when nothing is running is fine — it just tells you there's nothing to stop.

Use --dir <path> if your config isn't in ./vault-cortex.

get-sync-token

Generate an Obsidian Sync auth token — needed for remote setups — without leaving the CLI:

npx vault-cortex@latest get-sync-token

The command prompts for your Obsidian account email, password, and MFA code (if enabled), signs in via the Obsidian API, and prints the token. Use --dir <path> to write the token straight into an existing .env instead:

npx vault-cortex@latest get-sync-token --dir ./vault-cortex

During init --mode remote, this flow is offered automatically.

Requirements

• Node.js >= 22.12 (only for this CLI — the server itself runs in Docker)
• Docker or a Docker-compatible runtime (e.g. OrbStack, Colima, Podman) to run the server — the CLI manages the container through the docker command (on Linux, see Docker Engine)

Docs

• Local quickstart
• Remote quickstart (VPS + Obsidian Sync)
• One-click deploy on Render or Railway
• Full project README