Skip to main content

​
Self-Hosting Requirements

OpenSync can run on managed cloud services or on your own infrastructure. This page covers what you need for each approach.

​
Cloud deployment

The standard deployment uses these managed services:
Most individual developers and small teams will stay within free tiers for Convex, WorkOS, and Netlify. The main variable cost is OpenAI embeddings, which run about $0.02 per 1M tokens. A typical coding session generates roughly 2K-10K tokens of searchable text, so embedding costs are negligible.

​
What Convex handles

Convex serves as the entire backend for OpenSync. There is no separate server or API layer to deploy. Convex provides:
  • Real-time database with automatic sync to connected clients
  • Serverless functions for queries, mutations, and actions
  • HTTP endpoints for the plugin sync API (/sync/session, /sync/message, etc.)
  • Full-text search indexes for keyword search across sessions
  • Vector search indexes for semantic search with 1536-dimension OpenAI embeddings
  • File storage for daily wrapped images and profile photos
  • Scheduled functions for background processing like embedding generation
All backend logic lives in the convex/ directory of the repository.

​
What WorkOS handles

WorkOS AuthKit provides authentication with zero configuration for OAuth providers:
  • GitHub sign-in
  • Google sign-in
  • Email/password sign-in
  • Session management and token refresh
WorkOS is configured through environment variables. See the WorkOS setup guide for details.

​
100% Local deployment

For air-gapped environments or developers who want full control:
Running fully local requires modifying authentication logic and embedding generation. The codebase assumes Convex Cloud and WorkOS by default. See the Fork Guide for instructions on customizing these components.

​
System requirements

For local development:
  • Node.js 18 or later
  • npm 9+ or bun 1.0+
  • Git for cloning the repository
No Docker or container runtime is needed. Convex runs as a cloud service and the frontend is a standard Vite/React app.

​
Environment variables

All configuration is done through environment variables. Here is the minimum set for a cloud deployment:
For the complete list with descriptions, see Environment Variables.

​
Architecture overview

Plugins authenticate using API keys generated in the dashboard Settings. Each API call includes an Authorization: Bearer osk_... header that maps to a user account.

​
Next steps

Quick Start

Convex Backend

WorkOS Auth

Environment Variables