Sync with Cloud Storage

In this guide you will connect one or more cloud storage providers to your Lifestream Vault and configure bidirectional sync. Documents you create in Google Drive, Dropbox, or OneDrive will appear in your vault, and documents you create or edit in your vault will be pushed back to cloud storage.

By the end you will have:

• A connector configured for your chosen cloud provider (Google Drive, Dropbox, and/or OneDrive)
• An understanding of how bidirectional sync works — filesystem as source of truth, only .md files indexed
• Control over the sync direction (pull, push, or bidirectional) per connector
• Scripts to manually trigger sync, list connectors, and disconnect them via the SDK or CLI

Connecting Google Drive uses the standard OAuth 2.0 authorization code flow. Lifestream Vault requests read/write access to a specific Google Drive folder — it does not request access to your entire Drive.

Via the UI: navigate to Settings → Connectors → Add Connector → Google Drive, choose the vault you want to sync, and click Authorize with Google. You will be redirected to Google's consent screen, then back to your vault with the connector active.

To connect programmatically, obtain an authorization URL from the API and redirect the user (or open a browser window) to it:

import { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';

const { client } = await LifestreamVaultClient.login(
  'https://vault.lifestreamdynamics.com',
  'you@example.com',
  'your-password',
);

const VAULT_ID = 'vlt_abc123';

// OAuth authorization happens via the dedicated provider callback route
// (/api/v1/auth/google-drive/callback) — there is no connectors.getAuthUrl().
// Once the OAuth grant is stored, register the connector. create() takes a
// single params object (provider/name/vaultId/syncDirection/syncPath?).
// Note the provider value uses an underscore: 'google_drive'.
const connector = await client.connectors.create({
  provider: 'google_drive',
  name: 'Google Drive — my vault',
  vaultId: VAULT_ID,
  syncDirection: 'bidirectional',
  syncPath: 'Lifestream Vault/my-vault', // path prefix in Google Drive
});

console.log('Connector created:', connector.id);
console.log('Status:', connector.status);

The Dropbox connector uses the Dropbox OAuth 2.0 flow with PKCE. It syncs a specific folder in your Dropbox (not your entire Dropbox) to a vault. Only .md files within the folder are synced; other file types are ignored during indexing but are not deleted from Dropbox.

Via the UI: navigate to Settings → Connectors → Add Connector → Dropbox, choose your vault and the Dropbox folder path, and click Authorize with Dropbox.

// Authorize Dropbox via its OAuth callback route
// (/api/v1/auth/dropbox/callback), then register the connector.
const connector = await client.connectors.create({
  provider: 'dropbox',
  name: 'Dropbox — my vault',
  vaultId: VAULT_ID,
  syncDirection: 'bidirectional',
  syncPath: '/vault-sync/my-vault', // Dropbox path (absolute from root)
});

console.log('Dropbox connector created:', connector.id);

The OneDrive connector authenticates via Microsoft Identity Platform (Azure AD OAuth 2.0). It syncs a specific OneDrive folder to your vault. Both personal Microsoft accounts and Microsoft 365 work accounts are supported.

Via the UI: navigate to Settings → Connectors → Add Connector → OneDrive, choose your vault, and click Authorize with Microsoft.

// Authorize Microsoft via its OAuth callback route
// (/api/v1/auth/onedrive/callback), then register the connector.
const connector = await client.connectors.create({
  provider: 'onedrive',
  name: 'OneDrive — my vault',
  vaultId: VAULT_ID,
  syncDirection: 'pull', // pull-only: OneDrive → Vault
  syncPath: 'Documents/Lifestream Vault/my-vault',
});

console.log('OneDrive connector created:', connector.id);

Understanding the sync architecture helps you reason about what happens during conflicts and how changes propagate.

Filesystem as source of truth: Lifestream Vault stores documents as files on disk at {DATA_DIR}/{userId}/{vaultSlug}/{path}.md. The PostgreSQL database holds metadata (title, tags, timestamps, search index) derived from the files. The filesystem is always authoritative — if a file changes, the database is updated to match.

Only .md files are indexed: The connector sync worker only processes Markdown files (.md extension). Other file types (images, PDFs, spreadsheets) in your cloud storage folder are ignored during indexing. They are not deleted from cloud storage — they simply do not appear in your vault's document list or search index.

The sync cycle:

1. The connector-sync BullMQ worker runs on a schedule (every 15 minutes by default) or when triggered manually
2. For pull sync: the worker fetches changed files from cloud storage since the last sync timestamp and writes them to disk
3. For push sync: the worker reads files modified since the last sync from disk and uploads them to cloud storage
4. For bidirectional sync: both directions run in sequence — pull first, then push
5. After each cycle, the Chokidar file watcher detects any new/changed files on disk and updates the database metadata

Conflict resolution: If the same file is modified in both cloud storage and on disk since the last sync, the cloud storage version wins during the next pull cycle. The on-disk version is overwritten. If you need to preserve local changes, push them first (trigger a manual sync in push direction) before the automatic pull cycle runs.

When creating a connector, you choose how changes flow between your vault and cloud storage. You can change the direction at any time without disconnecting and reconnecting.

When to use each direction:

• Pull only — you use Obsidian or another tool that syncs to Google Drive/Dropbox/OneDrive, and you want your vault to reflect whatever is in cloud storage. The vault web editor remains usable but changes will be overwritten on the next pull cycle.
• Push only — you write primarily in the Lifestream Vault editor and want a backup in cloud storage, or you want to share documents with team members via Dropbox without giving them vault access.
• Bidirectional — the most flexible option, but requires care to avoid conflicts. Works best when team members do not edit the same files simultaneously in both systems.

// update is positional: (connectorId, params)
const updated = await client.connectors.update('con_abc123', {
  syncDirection: 'push', // was 'bidirectional'
});

console.log('Sync direction updated to:', updated.syncDirection);

Once a connector is set up, you can list all connectors for a vault, trigger an immediate sync (without waiting for the next scheduled cycle), and disconnect a connector when it is no longer needed.

Triggering a manual sync is useful after making a batch of changes that you want reflected immediately, or after updating the sync direction.

// List connectors — list(vaultId?) takes the vault ID directly (optional)
const connectors = await client.connectors.list(VAULT_ID);

for (const connector of connectors) {
  console.log(
    `[${connector.provider}] ${connector.id} | direction: ${connector.syncDirection} | status: ${connector.status} | last sync: ${connector.lastSyncAt ?? 'never'}`,
  );
}

// Trigger an immediate manual sync — sync(connectorId) is positional
const syncResult = await client.connectors.sync('con_abc123');
console.log('Sync enqueued:', syncResult);

// Inspect sync history via logs(connectorId) — there is no getSyncJob method
const logs = await client.connectors.logs('con_abc123');
for (const log of logs) {
  console.log(log);
}

// Disconnect a connector (does not delete synced files) — delete(connectorId)
await client.connectors.delete('con_abc123');
console.log('Connector disconnected.');

Map a Dedicated Folder

Point your connector at a dedicated folder in cloud storage (e.g., Lifestream Vault/my-vault) rather than a root folder or a folder that contains non-Markdown files. This keeps the sync scope narrow and reduces the time spent scanning for .md files.

Use Pull-Only for Obsidian + Vault Combos

If you use Obsidian with its built-in Obsidian Sync or a third-party sync (iCloud, Dropbox, etc.) as your primary editing environment, set the Lifestream Vault connector to pull only. This gives you the best of both worlds: Obsidian for offline, feature-rich editing and Lifestream Vault for web access, sharing, and publishing.

Avoid Editing the Same File in Both Systems Simultaneously

In bidirectional mode, the cloud storage version wins on the next pull cycle. If you are simultaneously editing a file in Google Drive and in the vault editor, the last system to sync wins and the other's changes are overwritten. Coordinate with your team to avoid simultaneous cross-system edits on the same file.

Watch Out for Non-Markdown Files

Cloud storage folders often contain images, PDFs, or spreadsheets alongside Markdown notes. Lifestream Vault ignores these for indexing purposes, but does not delete them. If you need images referenced in Markdown files, host them separately (a CDN, Cloudinary, or a public GitHub repo) and reference them by absolute URL.

Trigger Manual Sync After Bulk Uploads

After batch-uploading many documents to cloud storage (e.g., migrating from Notion or Bear), trigger a manual sync immediately rather than waiting for the next scheduled cycle. This gets your documents into the vault search index faster.

Monitor Sync Errors

Check the connector's sync job history periodically — especially after a large initial sync. Common errors include files with invalid characters in their names, files exceeding the 10 MB document size limit, or OAuth token expiry (which requires re-authorising the connector).

You now have cloud storage sync configured and understand how the bidirectional sync engine works. Here are some places to explore next:

• SDK Connectors Reference — full API surface for client.connectors: create, list, update, sync, delete, and manage sync jobs
• Automate Your Vault Guide — fire webhooks when synced documents are created or updated, triggering downstream automation
• Create a Blog Guide — publish documents synced from Dropbox or Google Drive as a public blog with a custom domain
• CLI Connectors Reference — all lsvault connectors commands and flags
• Manage Projects with Calendar — use frontmatter due dates in synced documents to power the vault calendar heatmap and due-date notifications