Skip to main content

​
Self-Hosting Requirements

The standard OpenSync setup uses your own Convex Cloud project for the React/Vite frontend, database, backend functions and file storage. The frontend is served by the @convex-dev/static-hosting component. WorkOS handles sign-in. Deploying your own OpenSync instance this way uses managed infrastructure. Running the Convex backend on your own server is a separate, advanced setup described below.

​
Accounts and services

Use any DNS provider that supports the records required by your services. Start with the URLs assigned to your Convex deployment if you do not need a custom domain. Review current provider pricing and limits for your expected usage. Custom-domain features may require paid plans; do not assume every feature is included in a free tier.

​
Development tools

  • Node.js 24 LTS, the version used to validate the current release.
  • npm, included with Node.js; use the repository’s package-lock.json with npm ci.
  • Git to clone and maintain your fork.
  • Access to your own Convex project and WorkOS application.
Docker is not required for the managed Convex Cloud setup. The frontend builds with Vite; its static output is uploaded to Convex.

​
Choose the static-hosting release

The reviewed static-hosting source is on the codex/convex-static-hosting-release branch, at commit bdb6ad0. It has been deployed to the hosted app; it has not yet been merged into the repository’s main branch. Use that reviewed release when following this page. The default branch still contains the earlier application baseline. These guides describe the reviewed static-hosting release. Do not deploy unrelated local feature work as part of setting up hosting.

​
Convex setup

Your reviewed checkout must register the static-hosting component in convex/convex.config.ts and serve it from convex/http.ts. Keep existing API and webhook routes before the static SPA fallback so frontend routing does not intercept them. Use separate Convex development and production deployments. Configure each deployment deliberately, deploy its backend functions, then publish the frontend assets to that same deployment. Uploading a frontend does not deploy backend changes. Convex provides the database, real-time subscriptions, server functions, plugin sync HTTP endpoints, search indexes, scheduled work and file storage. You do not need a separate frontend hosting account for this setup. The Convex static-hosting component serves the dashboard through HTTP actions. The browser’s Convex client connects to the deployment’s cloud API URL (.convex.cloud or its verified custom domain) for queries, mutations and live subscriptions. Plugins use the HTTP actions URL (.convex.site or its verified custom API domain). These are different endpoints; do not substitute one for the other.

​
WorkOS setup

Create your own WorkOS application and enable the sign-in methods you intend to offer. Production OAuth providers require their own configuration; do not assume they are enabled automatically. Before publishing the frontend:
  1. Register its exact callback URL in WorkOS, ending in /callback.
  2. Allow its origin in WorkOS CORS for the current browser authentication flow.
  3. Configure the application homepage, login and sign-out URLs for that origin.
  4. Set the matching WorkOS client ID in both the frontend build and Convex backend.
For example, an app at https://app.example.com uses callback https://app.example.com/callback and origin https://app.example.com. Keep development and production settings separate. WorkOS custom sign-in and email domains are optional. The hosted OpenSync release uses signin.opensync.dev for AuthKit and the default api.workos.com authentication API. Changing frontend hosting does not require changing token storage or the authentication issuer. See WorkOS AuthKit for the authentication integration.

​
Configuration and secrets

Public frontend values are baked into the Vite build:
These are examples: replace them with your own deployment and WorkOS application values. The static-hosting uploader supplies VITE_CONVEX_URL when used with --build. Set backend configuration on the intended Convex deployment: Store private API keys in Convex environment variables. Never prefix private keys with VITE_ or place them in the frontend bundle. The current hosted browser-auth flow does not require WORKOS_COOKIE_PASSWORD; a different server-session integration may have additional requirements. The repository’s deploy:static:prod script pins hosted OpenSync’s public WorkOS client and callback. Forks must replace those values or use the static-hosting uploader with their own build configuration. Never deploy a fork to OpenSync’s production or development project. See Environment Variables for the configuration reference.

​
Optional email

To enable app email, use your own Resend account, verified sending domain, API key and webhook signing secret. Set RESEND_FROM_EMAIL to a sender on that domain and point the signed delivery webhook at your own Convex HTTP endpoint, /resend-webhook. Product-update emails also need EMAIL_POSTAL_ADDRESS for the unsubscribe footer. Keep RESEND_TEST_MODE=true until you deliberately enable delivery. The current admin console allows search, drafts and previews in test mode but blocks sending. Fork owners must replace the hosted owner’s email allowlist in convex/lib/adminPolicy.ts with their own verified identities before using the owner console. A client-supplied email or database role does not grant access.

​
Optional custom domains

Add the custom domain in the correct Convex deployment and copy the verification TXT and destination records it provides. For Cloudflare, use DNS-only records for the Convex CNAMEs. Verify HTTPS before routing users to the domain, then register its exact frontend callback and origin in WorkOS. Hosted OpenSync uses www.opensync.dev for the frontend and api.opensync.dev for HTTP actions; both target production Convex. The apex redirects to www, preserving the path and query. app.opensync.dev is the Convex client API domain, not the dashboard URL. Production uses CONVEX_CLOUD_URL=https://app.opensync.dev and CONVEX_SITE_URL=https://api.opensync.dev as its canonical overrides. Use your own domain names for a fork; never point your fork at these hosted endpoints. For hosted plugin setup, copy https://api.opensync.dev from Settings. Existing plugin configurations remain valid. The currently published OpenCode and Claude Code login commands still require a Convex URL; Settings includes a compatibility URL for them.

​
Running the backend yourself

Convex supports running its backend on your own servers. That is different from publishing frontend assets with the static-hosting component on Convex Cloud. You become responsible for operating, securing, backing up and upgrading that backend. OpenSync is not a turnkey offline or air-gapped application: the standard configuration relies on WorkOS and optionally OpenAI and Resend. A fully local deployment requires replacing those integrations, preserving authentication and authorization, and adapting embedding generation and indexes if the model changes. Do not disable authentication on a publicly reachable instance. Start with the official Convex self-hosting guide and review the Fork Guide. This hosting migration did not validate a fully local deployment.

​
Release scope

The hosted app uses Convex static hosting and includes the focused owner console and opt-in public usage leaderboard. Other local product work, including teams, user moderation, the evaluation leaderboard and the larger in-app documentation redesign, has not been released. Review the exact checkout you deploy instead of assuming all local changes match the hosted app.

​
Next steps

Quick Start

Convex Backend

Static Hosting Component

WorkOS Auth