Real-time sync daemon for convex-versioned-assets - mirrors Convex assets to local filesystem
npm install convex-versioned-assets-syncReal-time sync daemon for convex-versioned-assets - mirrors your Convex assets to the local filesystem.
- 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
- 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
``bashInstall globally
npm install -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:
bash
Install the component
npm install convex-versioned-assetsRun the setup (creates required Convex functions)
npx convex-versioned-assets setupDeploy to Convex
npx convex dev
`Make sure your
file contains:`env
CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_ADMIN_KEY=your-admin-key
`Usage
$3
bash
Navigate to your project directory
cd /path/to/myprojectInstall the daemon (uses folder name as project name)
convex-versioned-assets-sync installOr 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
$3
bash
Run directly in foreground
convex-versioned-assets-sync run
`$3
bash
List all installed daemons
convex-versioned-assets-sync listUninstall a daemon
convex-versioned-assets-sync uninstall --name myprojectView logs
tail -f ~/Library/Logs/ConvexSync/myproject/stdout.logStop/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
file)
3. Config file (~/.convex-sync.toml)
4. Default values$3
| 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 |$3
`toml
sync_dir = "./versioned-assets"
concurrency = 10
`Multiple Projects
You can run separate sync daemons for different projects:
bash
Project 1 (uses folder name "project1")
cd /path/to/project1
convex-versioned-assets-sync installProject 2 (uses folder name "project2")
cd /path/to/project2
convex-versioned-assets-sync installEach 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
$3
Run the setup command in the main package:
bash
npx convex-versioned-assets setup
npx convex dev
`$3
Make sure
in your .env matches the one set in your Convex deployment environment variables.$3
Check the logs:
`bash
tail -f ~/Library/Logs/ConvexSync/myproject/stderr.log
`$3
Delete the state file and restart:
bash
rm .convex-sync-state.json
convex-versioned-assets-sync uninstall --name myproject
convex-versioned-assets-sync install --name myproject
``MIT