AWS Reference Deployment

Relevant source files

• .env.example
• .github/workflows/deploy.yml
• .github/workflows/force_deploy.yml
• .github/workflows/gitleaks.yml
• .github/workflows/scorecard.yml
• .github/workflows/test_deploy.yml
• .github/workflows/trivy.yml
• DEPLOY.md
• Dockerfile
• RECOVERY.md
• eslint.config.ts
• scripts/dev.ts
• scripts/generate-dockerhub-readme.ts
• src/functions/authorizer.ts
• src/jwt.ts
• sst.config.ts

The AWS reference deployment provides a production-grade, remote-accessible infrastructure for Vault Cortex. It uses SST v4 (Ion) for Infrastructure-as-Code (IaC) to provision a defense-in-depth architecture. This setup enables access to your Obsidian vault from any MCP client globally while maintaining a rigorous security posture across three independent boundaries.

Architecture Overview

The reference deployment utilizes AWS Lightsail for cost-effective container hosting and API Gateway for managed HTTPS and authentication.

Component Interaction

The system follows a tiered data flow where requests are validated at the edge before reaching the application.

1. API Gateway: Terminates TLS and executes a path-aware Lambda authorizer src/functions/authorizer.ts49-51
2. Lambda Authorizer: Validates tokens for protected routes while allowing OAuth discovery and health checks to pass through src/functions/authorizer.ts34-47
3. Lightsail Instance: Runs a Docker Compose stack containing the vault-cortex:remote image which bundles the MCP server and an obsidian-sync process supervised by s6-overlay Dockerfile5-7 DEPLOY.md94-95
4. Application Layer: The Express server performs secondary token validation as defense-in-depth, using the same secret linked to the Lambda authorizer src/functions/authorizer.ts67-81

Data Flow and Code Entities

This diagram maps the natural language components to their specific code entities and infrastructure definitions.

"AWS Reference Infrastructure Map"

Sources: sst.config.ts21-158 src/functions/authorizer.ts49-51 DEPLOY.md3-4 scripts/dev.ts173-179

Security Posture: Defense in Depth

The reference deployment implements three independent security boundaries to protect personal vault data.

Boundary	Implementation	Responsibility
Transport	API Gateway + ACM	TLS termination and automatic certificate management sst.config.ts52-59
Edge Auth	Lambda Authorizer	Path-aware validation (Static Token or JWT) src/functions/authorizer.ts71-81
App Auth	Express Middleware	Secondary validation of MCP_AUTH_TOKEN in-process src/functions/authorizer.ts7-8

Lambda Authorizer Logic

The authorizer (handler) distinguishes between "Open Paths" (OAuth discovery, health checks) and "Protected Paths" (MCP protocol endpoints) src/functions/authorizer.ts34-47 It is implemented in src/functions/authorizer.ts and consumes the McpAuthToken SST secret src/functions/authorizer.ts67-71

"Authorizer Decision Flow"

Sources: src/functions/authorizer.ts34-85 sst.config.ts97-98 src/jwt.ts50-78

Infrastructure Configuration (sst.config.ts)

The SST configuration defines the hardware and networking requirements. It uses the aws.lightsail provider to manage compute and static networking resources.

• Compute: Defaults to medium_3_0 (4GB RAM, 2 vCPU) to provide headroom for concurrent ONNX inference and page-cache sst.config.ts124-128 It is configured with protect: true and retainOnDelete: true to prevent accidental destruction sst.config.ts135-140
• Secrets: The McpAuthToken is managed as an sst.Secret, encrypted in S3 and linked to the Lambda authorizer sst.config.ts97-98
• Networking: Supports custom domains via CUSTOM_DOMAIN and CUSTOM_DOMAIN_CERT_ARN sst.config.ts52-59 It also supports firewall CIDR restrictions for SSH (SSH_CIDRS) and the MCP port (MCP_PORT_CIDRS) sst.config.ts32-38
• Access: Provisions a dedicated SSH keypair (VaultCortexKey) for deployment, shared between local dev and CI to avoid instance replacement sst.config.ts99-121

Sources: sst.config.ts11-158

Container Orchestration

The Lightsail instance runs the vault-cortex:remote image, which bundles the MCP server and Obsidian Sync sidecar under s6-overlay supervision Dockerfile5-7 scripts/dev.ts55

Environment Integration

The containers receive configuration via a .env file generated during the deployment process scripts/dev.ts176-177 Key variables include:

• Obsidian Credentials: VAULT_NAME and OBSIDIAN_AUTH_TOKEN for the sync process DEPLOY.md60-62
• Search Config: EMBEDDING_ENABLED and RERANK_MODE for the hybrid search pipeline DEPLOY.md64
• Memory Layer: MEMORY_ENABLED and MEMORY_DIR for the personalization engine DEPLOY.md64
• Persistence: Volumes are managed by Docker Compose on the Lightsail host disk DEPLOY.md94

Sources: DEPLOY.md55-64 scripts/dev.ts145-185

Deployment Lifecycle

The deployment process is managed via GitHub Actions or the scripts/dev.ts helper script, ensuring idempotency and security.

Deployment Workflow

The deploy.yml workflow orchestrates the full stack update:

1. Infrastructure: npx sst deploy updates AWS resources .github/workflows/deploy.yml80
2. Image Build: Builds a multi-arch Docker image targeting the remote stage and pushes to GHCR .github/workflows/deploy.yml159-172
3. Bootstrap: Connects to Lightsail via SSH, ensures /opt/vault-cortex exists, and logs into GHCR on the instance scripts/dev.ts157-172
4. Orchestration: SCPs docker-compose.yml and .env, then runs docker compose pull && up -d --wait scripts/dev.ts173-179

Recovery and Maintenance

• Auto-Snapshots: Lightsail takes daily snapshots at 03:00 UTC with a 7-day rolling retention, capturing the full boot disk including Docker volumes sst.config.ts130-133
• Manual Recovery: Documentation in DEPLOY.md covers monitoring and troubleshooting DEPLOY.md117-158
• Helper Script: scripts/dev.ts provides subcommands for docker:publish and lightsail:up to facilitate local-to-cloud updates scripts/dev.ts131-185
• Testing: The test_deploy.yml workflow allows deploying any branch to a :test tag for verification without affecting production release artifacts .github/workflows/test_deploy.yml8-13

Sources: DEPLOY.md82-95 .github/workflows/deploy.yml1-185 scripts/dev.ts1-192 .github/workflows/test_deploy.yml1-150 sst.config.ts130-133