convex-versioned-assets-sync

Real-time sync daemon for convex-versioned-assets - mirrors your Convex assets to the local filesystem.

Features

• Real-time sync via WebSocket subscription
• Initial sync on first run (catches up on all existing assets)
• Incremental updates using changelog cursors (never misses changes)
• macOS launchd integration for auto-start on boot
• Multiple project support - run separate daemons for different projects

Prerequisites

• Bun runtime (v1.0.0 or later)
• convex-versioned-assets component set up in your Convex project
• CONVEX_URL and CONVEX_ADMIN_KEY in your project's .env file

Installation

# Install globally
npm install -g convex-versioned-assets-sync

# Or with bun
bun add -g convex-versioned-assets-sync

Setup

Before using the sync daemon, you need to set up the convex-versioned-assets component in your Convex project:

# Install the component
npm install convex-versioned-assets

# Run the setup (creates required Convex functions)
npx convex-versioned-assets setup

# Deploy to Convex
npx convex dev

Make sure your .env file contains:

CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_ADMIN_KEY=your-admin-key

Usage

Install as a Background Daemon (Recommended)

# Navigate to your project directory
cd /path/to/myproject

# Install the daemon (uses folder name as project name)
convex-versioned-assets-sync install

# Or with explicit name
convex-versioned-assets-sync install --name custom-name

The daemon will:

• Start immediately and perform an initial sync
• Auto-start on system boot (macOS)
• Restart automatically if it crashes

Manual Run (for testing)

# Run directly in foreground
convex-versioned-assets-sync run

Managing Daemons

# List all installed daemons
convex-versioned-assets-sync list

# Uninstall a daemon
convex-versioned-assets-sync uninstall --name myproject

# View logs
tail -f ~/Library/Logs/ConvexSync/myproject/stdout.log

# Stop/start manually
launchctl unload ~/Library/LaunchAgents/com.convex-versioned-assets.sync.myproject.plist
launchctl load ~/Library/LaunchAgents/com.convex-versioned-assets.sync.myproject.plist

Configuration

The daemon reads configuration from multiple sources (in order of precedence):

1. Command-line arguments
2. Environment variables (from .env file)
3. Config file (~/.convex-sync.toml)
4. Default values

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CONVEX_URL | Your Convex deployment URL | (required) | | CONVEX_ADMIN_KEY | Admin key for authentication | (required) | | CONVEX_SYNC_DIR | Directory to sync assets to | ./versioned-assets | | CONVEX_SYNC_CONCURRENCY | Parallel download limit | 10 |

Config File (~/.convex-sync.toml)

sync_dir = "./versioned-assets"
concurrency = 10

Multiple Projects

You can run separate sync daemons for different projects:

# Project 1 (uses folder name "project1")
cd /path/to/project1
convex-versioned-assets-sync install

# Project 2 (uses folder name "project2")
cd /path/to/project2
convex-versioned-assets-sync install

# Each has independent logs and state
tail -f ~/Library/Logs/ConvexSync/project1/stdout.log
tail -f ~/Library/Logs/ConvexSync/project2/stdout.log

How It Works

1. Initial Sync: On first run, fetches all folders and files from your Convex deployment
2. Cursor Tracking: Stores a compound cursor (timestamp + ID) to track sync position
3. WebSocket Subscription: Subscribes to real-time changelog updates
4. File Management: Downloads new/updated files, deletes removed files, handles renames and moves
5. Version Tracking: Uses extended attributes (xattr) to track file versions locally

Troubleshooting

"Missing required Convex function" error

Run the setup command in the main package:

npx convex-versioned-assets setup
npx convex dev

"Authentication failed" error

Make sure CONVEX_ADMIN_KEY in your .env matches the one set in your Convex deployment environment variables.

Daemon not starting

Check the logs:

tail -f ~/Library/Logs/ConvexSync/myproject/stderr.log

Reset sync state

Delete the state file and restart:

rm .convex-sync-state.json
convex-versioned-assets-sync uninstall --name myproject
convex-versioned-assets-sync install --name myproject

License

MIT