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:
| Service | Purpose | Required | Free tier |
|---|
| Convex | Real-time database, backend functions, file storage | Yes | 1M function calls/month |
| WorkOS | Authentication via AuthKit (GitHub, Google, email) | Yes | 1M MAUs |
| OpenAI | text-embedding-3-small for semantic search | Optional | Pay-as-you-go |
| Netlify or Vercel | Static frontend hosting | Yes | Generous free tier |
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:
| Component | Cloud service | Local alternative |
|---|
| Database & backend | Convex Cloud | Convex self-hosted (when available) |
| Authentication | WorkOS | Disable auth or use a local provider |
| Embeddings | OpenAI API | Local models via Ollama (nomic-embed-text, etc.) |
| Frontend | Netlify/Vercel | Any static file server (npx serve dist/) |
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:
# Frontend (Vite)
VITE_CONVEX_URL=https://your-deployment.convex.cloud
VITE_WORKOS_CLIENT_ID=client_...
# Convex backend (set via npx convex env set)
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_COOKIE_PASSWORD=a-random-string-at-least-32-characters
# Optional: enables semantic search
OPENAI_API_KEY=sk-...
Architecture overview
CLI Tool (OpenCode, Claude, Cursor, etc.)
|
v
Sync Plugin (npm package, runs locally)
|
v HTTPS POST /sync/session, /sync/message
|
Convex HTTP Endpoints (convex/http.ts)
|
v
Convex Database (sessions, messages, parts, embeddings)
|
v
React Dashboard (Vite, served from Netlify/Vercel)
|
v
User's browser (real-time subscriptions via Convex client)
Authorization: Bearer osk_... header that maps to a user account.
Next steps
