Convex Backend

OpenSync’s entire backend runs on Convex. There is no separate server, no Docker containers, and no infrastructure to manage. Convex provides the database, serverless functions, real-time subscriptions, HTTP endpoints, file storage, and scheduled jobs.

One-click deploy

The fastest way to set up the backend:

This creates:

A new Convex project linked to your account
All database tables with their schemas and indexes
Serverless functions for queries, mutations, and actions
HTTP endpoints for the sync API (/sync/session, /sync/message, /sync/batch, /search, etc.)
Search indexes for full-text search
Vector indexes for semantic search
Scheduled function support for background embedding generation

Manual deploy

1. Install the Convex CLI

npm install -g convex

2. Clone and initialize

git clone https://github.com/waynesutton/opensync
cd opensync
npm install
npx convex dev

On first run, the CLI prompts you to:

Sign in to your Convex account (or create one).
Create a new project.
Push the schema, functions, and indexes.

npx convex dev runs in watch mode. It pushes changes to your development deployment every time you save a file in the convex/ directory.

3. Set environment variables

npx convex env set WORKOS_API_KEY sk_your_key
npx convex env set WORKOS_CLIENT_ID client_your_id
npx convex env set OPENAI_API_KEY sk-your-key  # Optional, for semantic search

4. Deploy to production

npx convex deploy

This pushes your functions and schema to the production deployment. Production deployments have a separate URL from development.

Database schema

The Convex backend defines these tables:

Table	Purpose	Key fields
`users`	User accounts	`workosId`, `email`, `name`, `apiKey`
`sessions`	AI coding sessions	`userId`, `externalId`, `source`, `model`, `totalTokens`, `cost`
`messages`	Messages within sessions	`sessionId`, `externalId`, `role`, `textContent`
`parts`	Message content blocks	`messageId`, `type` (text, tool-call, tool-result)
`sessionEmbeddings`	Vector embeddings for sessions	`sessionId`, `embedding` (1536-dim), `textHash`
`messageEmbeddings`	Vector embeddings for messages	`messageId`, `embedding` (1536-dim)
`apiLogs`	API request logs	`userId`, `endpoint`, `statusCode`
`dailyWrapped`	Daily activity summaries	`userId`, `date`, stats
`docPages`	Documentation page metadata	`slug`, `title`, `content`
`docEmbeddings`	Documentation search embeddings	`docPageId`, `embedding`

Indexes

Key indexes defined in the schema:

Table	Index	Fields	Purpose
`sessions`	`by_user`	`userId`	List sessions for a user
`sessions`	`by_user_external`	`userId`, `externalId`	Dedup during sync
`sessions`	`by_user_and_source`	`userId`, `source`	Filter by tool
`messages`	`by_session`	`sessionId`	List messages in a session
`messages`	`by_external_id`	`externalId`	Dedup during sync

Search indexes enable full-text search on sessions.searchableText. Vector indexes enable cosine similarity search on sessionEmbeddings.embedding.

HTTP endpoints

The sync API is defined in convex/http.ts. These are the endpoints that plugins call:

Endpoint	Method	Purpose
`/sync/session`	POST	Create or update a session
`/sync/message`	POST	Create or update a message
`/sync/batch`	POST	Bulk sync sessions and messages
`/search`	POST	Full-text, semantic, or hybrid search
`/health`	GET	Health check (no auth required)
`/api/sessions`	GET	List sessions
`/api/sessions/:id`	GET	Get session with messages
`/api/export`	GET	Export sessions in eval formats
`/api/context`	GET	Get context for RAG

All endpoints except /health require an Authorization: Bearer osk_... header.

Convex dashboard

Access your project at dashboard.convex.dev:

Data tab: Browse and edit documents in any table
Functions tab: See all deployed functions, their execution logs, and errors
Logs tab: Real-time function execution logs with timing and error details
Settings tab: Environment variables, deployment URLs, and project configuration

Scaling

Convex handles scaling automatically:

Aspect	How it scales
Functions	Scale to zero when idle, scale up under load
Database	Storage grows with usage, no provisioning needed
Real-time	WebSocket connections managed by Convex infrastructure
HTTP endpoints	Handle concurrent requests without configuration

The free tier includes 1 million function calls per month, which is sufficient for most individual developers. Teams with higher usage can upgrade through the Convex dashboard.

Monitoring

Function logs

Check dashboard.convex.dev > Logs for:

Function execution times
Error stack traces
Write conflict retries
Scheduled function results

Common issues

Write conflicts: If you see retry logs for mutations, check the write conflict patterns documentation. OpenSync’s mutations are designed to be idempotent, but rapid syncing from multiple plugins can occasionally trigger retries. Slow queries: Queries that scan many documents without using an index will be slow. All OpenSync queries use indexes by design, but custom modifications should follow the same pattern.

Getting Started

Dashboard

Plugins

API Reference

Search

Authentication

Hosting & Deploy

Fork & Self-Host

Troubleshooting

Convex Backend

Convex Backend

One-click deploy

Manual deploy

1. Install the Convex CLI

2. Clone and initialize

3. Set environment variables

4. Deploy to production

Database schema

Indexes

HTTP endpoints

Convex dashboard

Scaling

Monitoring

Function logs

Common issues

Next steps

Environment Variables

WorkOS Auth

Frontend Hosting

Fork Guide

​Convex Backend

​One-click deploy

​Manual deploy

​1. Install the Convex CLI

​2. Clone and initialize

​3. Set environment variables

​4. Deploy to production

​Database schema

​Indexes

​HTTP endpoints

​Convex dashboard

​Scaling

​Monitoring

​Function logs

​Common issues

​Next steps

Environment Variables

WorkOS Auth

Frontend Hosting

Fork Guide

Convex Backend

One-click deploy

Manual deploy

1. Install the Convex CLI

2. Clone and initialize

3. Set environment variables

4. Deploy to production

Database schema

Indexes

HTTP endpoints

Convex dashboard

Scaling

Monitoring

Function logs

Common issues

Next steps