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

# Environment Variables

> Complete environment variable reference

# Environment Variables

Complete reference for all environment variables.

## Required Variables

### Frontend (Vite)

```bash theme={null}
# Convex deployment URL
VITE_CONVEX_URL=https://your-deployment.convex.cloud
```

### Backend (Convex)

```bash theme={null}
# WorkOS authentication
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
```

### Hosting Platform

```bash theme={null}
# WorkOS cookie encryption
WORKOS_COOKIE_PASSWORD=a-secure-32-character-or-longer-password
```

## Optional Variables

### OpenAI (for semantic search)

```bash theme={null}
OPENAI_API_KEY=sk-...
```

## Variable Reference

| Variable                 | Required | Where             | Description                   |
| ------------------------ | -------- | ----------------- | ----------------------------- |
| `VITE_CONVEX_URL`        | Yes      | Frontend          | Convex deployment URL         |
| `WORKOS_API_KEY`         | Yes      | Convex            | WorkOS API key                |
| `WORKOS_CLIENT_ID`       | Yes      | Convex + Frontend | WorkOS client ID              |
| `WORKOS_COOKIE_PASSWORD` | Yes      | Frontend          | Cookie encryption key         |
| `OPENAI_API_KEY`         | No       | Convex            | OpenAI API key for embeddings |

## Setting Variables

### Convex

```bash theme={null}
# Via CLI
npx convex env set VARIABLE_NAME value

# View current values
npx convex env list
```

### Netlify

1. Go to **Site settings** > **Environment variables**
2. Click **Add a variable**
3. Enter key and value

### Vercel

1. Go to **Settings** > **Environment Variables**
2. Add variables for Production/Preview/Development

## Local Development

Create a `.env.local` file in the project root:

```bash theme={null}
# .env.local
VITE_CONVEX_URL=https://your-deployment.convex.cloud
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_COOKIE_PASSWORD=dev-password-at-least-32-characters
```

<Warning title="Never commit .env files">
  Add `.env.local` to `.gitignore` to prevent committing secrets.
</Warning>

## Generating Secrets

For `WORKOS_COOKIE_PASSWORD`:

```bash theme={null}
# macOS/Linux
openssl rand -base64 32

# Or use any password generator for a 32+ character string
```

## Troubleshooting

### "VITE\_CONVEX\_URL is undefined"

* Ensure the variable starts with `VITE_` for Vite to expose it
* Restart the dev server after adding variables

### "WorkOS authentication failed"

* Verify `WORKOS_API_KEY` and `WORKOS_CLIENT_ID` match your WorkOS dashboard
* Check that redirect URIs are configured

### "Cookie not set"

* `WORKOS_COOKIE_PASSWORD` must be at least 32 characters