Vault Cortex provides three distinct deployment modes that enable secure access to your Obsidian vault from anywhere. All modes run the same vault-cortex Docker image, which is built using a multi-stage, two-target Dockerfile Dockerfile1-7 These paths progress from a local-only setup to a fully remote, production-grade cloud architecture.
The deployment surface is designed around a single OCI image that interacts directly with .md files on disk using its own Obsidian-parity parsers. By removing the dependency on a running Obsidian desktop instance, Vault Cortex can be hosted on any infrastructure that supports Docker, Podman, or nerdctl deploy/remote/docker-compose.yml11-12 docker-compose.yml1-7
The choice of deployment mode depends on your requirements for mobility and infrastructure complexity. All modes can be scaffolded via the CLI using npx vault-cortex init DEPLOY.md66-68
| Mode | Use Case | Sync Mechanism | Image Target |
|---|---|---|---|
| Local | Single machine, low latency | Bind-mount (Direct FS) | local (:latest) |
| Remote | Access from any device | Obsidian Sync (Headless) | remote (:remote) |
| AWS Reference | Production-grade, mobile | Obsidian Sync (Headless) | remote (:remote) |
The simplest entry point. It runs a single container using the :latest image tag, which contains the MCP server alone under tini supervision Dockerfile3-4 Dockerfile56-57 Your vault folder is bind-mounted from the host machine. This mode includes a specific WINDOWS_MODE flag to enable polling for the file watcher and rename-based write strategies when hosting on Windows drives via Docker Desktop .env.example99-103
For details, see Local Docker Deployment.
This mode enables remote access from any device by bundling Obsidian Sync inside the container. It uses the :remote image tag, where s6-overlay supervises both the bidirectional obsidian-headless sync process and the MCP server Dockerfile5-7 Dockerfile90-91 This setup allows changes made by an AI on a remote server to propagate back to your phone or desktop via official Obsidian Sync deploy/remote/docker-compose.yml1-5
For details, see Remote Deployment with Obsidian Sync.
The full production setup, utilizing SST for Infrastructure-as-Code .github/workflows/deploy.yml71-80 It runs the :remote image on AWS Lightsail and provides a defense-in-depth security posture with three independent boundaries:
McpAuthToken before requests reach the container DEPLOY.md30-37vault-cortex server validates the bearer token in-process (Express middleware) as a final security check docker-compose.yml9-12For details, see AWS Reference Deployment.
The following diagram bridges high-level deployment concepts to specific code entities and infrastructure definitions.
"Natural Language Space" to "Code Entity Space"
Sources: Dockerfile90-131 docker-compose.yml16-21 deploy/remote/docker-compose.yml18-23 .github/workflows/deploy.yml71-80
The flow of data from an AI agent's request through the security layers to the vault filesystem and back to your other devices via sync.
"Client Request" to "Vault Sync"
Sources: docker-compose.yml9-12 docker-compose.yml38-39 Dockerfile5-7 Dockerfile126-130
The repository automates the building of both :latest (local target) and :remote (remote target) image targets for multiple architectures (linux/amd64, linux/arm64) .github/workflows/deploy.yml159-172 To maintain a high security posture, the build process uses a cache-busting APT_UPGRADE_DATE .github/workflows/deploy.yml133-136 This ensures that Debian security patches are applied at build time, covering the window between base image releases Dockerfile61-66
Sources: Dockerfile1-7 Dockerfile61-66 .github/workflows/deploy.yml133-136 .github/workflows/deploy.yml159-172
Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.