Remote Deployment with Obsidian Sync

Relevant source files

• .github/workflows/deploy.yml
• .github/workflows/test_deploy.yml
• DOCKERHUB.md
• Dockerfile
• deploy/local/README.md
• deploy/remote/.env.example
• deploy/remote/README.md
• deploy/remote/docker-compose.yml
• docker-compose.yml
• rootfs/etc/s6-overlay/scripts/init-check-auth
• rootfs/etc/s6-overlay/scripts/init-obsidian-login
• rootfs/usr/local/bin/get-sync-token
• templates/memory/README.md

The Remote Deployment mode is the primary production path for Vault Cortex, enabling secure access to an Obsidian vault from any device (mobile, web, or remote desktop). Unlike the local deployment which uses bind-mounts, the remote deployment utilizes the vault-cortex:remote image, which bundles Obsidian Sync to maintain a bidirectional, headless synchronization between the official Obsidian cloud and the Vault Cortex server Dockerfile5-7

This deployment architecture removes the requirement for a local Obsidian desktop instance or a persistent VPN connection, making the vault accessible via a standard MCP interface over HTTPS deploy/remote/docker-compose.yml3-5

Architecture Overview

The remote deployment is powered by a single OCI image supervised by s6-overlay. It manages two distinct processes: the obsidian-headless CLI for synchronization and the Vault Cortex MCP server docker-compose.yml3-5

Data Flow and Service Interaction

The following diagram illustrates the relationship between the external Obsidian Sync service, the internal supervised processes, and the shared volumes.

Remote Deployment Component Graph

Sources: Dockerfile5-7 docker-compose.yml17-65 deploy/remote/docker-compose.yml18-65

Supervision and Initialization

The container uses s6-overlay to manage the lifecycle and dependencies of the sync and MCP processes. The remote target in the Dockerfile installs s6-overlay and the obsidian-headless CLI (ob) Dockerfile90-131

1. Init Chain and Authentication

Before services start, the container executes an initialization chain defined in the rootfs/ directory:

• Auth Check: The init-check-auth script ensures OBSIDIAN_AUTH_TOKEN is present, failing early with instructions if it is missing rootfs/etc/s6-overlay/scripts/init-check-auth1-18
• Login Setup: init-obsidian-login handles the authentication state by running ob login as the obsidian user rootfs/etc/s6-overlay/scripts/init-obsidian-login1-15
• Token Retrieval: Users can generate the required OBSIDIAN_AUTH_TOKEN by running the container with the get-sync-token entrypoint, which provides an interactive login prompt rootfs/usr/local/bin/get-sync-token1-47

2. Service Definitions

• svc-obsidian-sync: A long-running service that executes ob sync. It uses DEVICE_NAME to identify itself to the Obsidian cloud docker-compose.yml23-31
• svc-vault-mcp: The MCP server process. It listens on port 8000 and depends on the sync process for data availability docker-compose.yml32-43 The container healthcheck validates this service by querying the /healthz endpoint docker-compose.yml70-81

Sources: Dockerfile90-131 docker-compose.yml23-81 rootfs/etc/s6-overlay/scripts/init-check-auth1-18 rootfs/etc/s6-overlay/scripts/init-obsidian-login1-15

Implementation Details

Shared Volumes and Permissions

To ensure both the sync process and the Node.js server can read and write to the same files, the deployment aligns permissions:

• The PUID and PGID environment variables (default 1000) map the internal obsidian user to the host user docker-compose.yml27-28
• Named Volumes: The deployment uses three named volumes to ensure data persistence docker-compose.yml86-93:
  • vault_data: The actual markdown vault files, mounted at /vault docker-compose.yml62
  • mcp_index_data: The SQLite search index, vector embeddings, and logs, mounted at /data docker-compose.yml63
  • obsidian_config: Stores the headless Obsidian login state and sync configuration, mounted at /home/obsidian/.config docker-compose.yml64

Security and HTTPS

Remote deployment requires HTTPS for secure communication and OAuth 2.1 compliance.

• PUBLIC_URL: This defines the base URL used in OAuth discovery metadata docker-compose.yml39
• In-Process Auth: While an upstream reverse proxy (like AWS API Gateway) handles TLS termination, the server validates the MCP_AUTH_TOKEN as defense-in-depth docker-compose.yml9-12

Sources: docker-compose.yml9-65 docker-compose.yml86-93 deploy/remote/docker-compose.yml62-65

Configuration Reference

The following table describes the primary environment variables used in the remote deployment mode.

Variable	Default	Description
OBSIDIAN_AUTH_TOKEN	Required	Token for Obsidian Sync cloud access docker-compose.yml24
VAULT_NAME	Required	The exact name of the vault to sync (case-sensitive) docker-compose.yml25
MCP_AUTH_TOKEN	Required	Bearer token for in-process MCP authentication docker-compose.yml38
PUBLIC_URL	Required	The public-facing HTTPS URL for OAuth metadata docker-compose.yml39
DEVICE_NAME	vault-cortex-lightsail	The name shown in Obsidian Sync settings docker-compose.yml29
CONFLICT_STRATEGY	merge	How to handle sync conflicts docker-compose.yml30
SYNC_MODE	bidirectional	Sync directionality docker-compose.yml31

Sources: docker-compose.yml22-61 deploy/remote/docker-compose.yml24-61

Operational Flow

Code-to-Entity Mapping: Startup and Sync

Sources: docker-compose.yml67-81 rootfs/etc/s6-overlay/scripts/init-check-auth1-18 rootfs/etc/s6-overlay/scripts/init-obsidian-login1-15 Dockerfile90-131

Deployment Steps

1. Token Generation: Run docker run --rm -it --entrypoint get-sync-token ghcr.io/aliasunder/vault-cortex:remote to get your sync token rootfs/usr/local/bin/get-sync-token1-10
2. Environment Setup: Copy .env.example to .env and provide the required keys deploy/remote/docker-compose.yml7-8
3. Provisioning: Execute docker compose up -d. The server will be healthy once the sync process completes its initial pull and the Node server responds to /healthz docker-compose.yml67-81
4. CLI Scaffolding: The fastest path is using the CLI: npx vault-cortex@latest init --mode remote deploy/remote/README.md29-31

Sources: docker-compose.yml1-94 deploy/remote/docker-compose.yml1-90 rootfs/usr/local/bin/get-sync-token1-47