> ## 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. # Convex Backend > Deploy and manage the Convex backend for OpenSync # Convex Backend OpenSync's entire backend runs on [Convex](https://convex.dev). 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: [![Deploy to Convex](https://convex.dev/button.svg)](https://convex.dev/new?template=waynesutton/opensync) 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 ```bash theme={null} npm install -g convex ``` ### 2. Clone and initialize ```bash theme={null} git clone https://github.com/waynesutton/opensync cd opensync npm install npx convex dev ``` On first run, the CLI prompts you to: 1. Sign in to your Convex account (or create one). 2. Create a new project. 3. 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 ```bash theme={null} 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 ```bash theme={null} 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](https://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](/troubleshooting/common-issues) 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. ## Next steps