Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opensync.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
ServicePurposeRequiredFree tier
ConvexReal-time database, backend functions, file storageYes1M function calls/month
WorkOSAuthentication via AuthKit (GitHub, Google, email)Yes1M MAUs
OpenAItext-embedding-3-small for semantic searchOptionalPay-as-you-go
Netlify or VercelStatic frontend hostingYesGenerous 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:
ComponentCloud serviceLocal alternative
Database & backendConvex CloudConvex self-hosted (when available)
AuthenticationWorkOSDisable auth or use a local provider
EmbeddingsOpenAI APILocal models via Ollama (nomic-embed-text, etc.)
FrontendNetlify/VercelAny 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-...
For the complete list with descriptions, see Environment Variables.

​
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)
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