Self-hosted: Configure Convex

Set up Convex deployments, auth, and local runtime for this project.

1) Create and link Convex project

Create a Convex project from dashboard (dev deployment first).
Copy deployment values into .env.local.
Run local sync and wait until functions are ready.

Initial project bootstrap

bun install
cp .env.local.example .env.local
bunx convex dev

Required baseline env vars

NEXT_PUBLIC_CONVEX_URL=https://<project>.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://<project>.convex.site
CONVEX_DEPLOYMENT=<deployment-key>
AUTH_GITHUB_ID=<github-client-id>
AUTH_GITHUB_SECRET=<github-client-secret>
AUTH_GOOGLE_ID=<google-client-id>
AUTH_GOOGLE_SECRET=<google-client-secret>

2) Configure auth provider

Create/update GitHub and Google OAuth apps and set callback URLs to Convex auth routes.
Ensure local callback and production callback are both configured where required.
Set OAuth client id/secret in both local env and production deployment secrets.
Verify callback returns to app domain and session persists after refresh.

Callback pattern to verify

https://<your-convex-site>.convex.site/api/auth/callback/github
https://<your-convex-site>.convex.site/api/auth/callback/google

3) Start local stack

Terminal A

bunx convex dev

Terminal B

bun run dev

After env changes

# restart both processes so runtime picks up new values
pkill -f "convex dev" || true
pkill -f "next dev" || true
bunx convex dev
bun run dev

4) Verify backend health

Workspace loads after login.
Tasks/documents mutations persist correctly.
Role checks and protected routes behave as expected.
No Convex auth route mismatch errors in logs.

Production readiness checks

- Login/logout cycle works on production domain
- Workspace create/switch flow works
- Mutations write successfully
- OpenClaw settings can be saved and re-read
- No 401/404 auth callback errors in production logs

5) Production deployment detail

Set all required env vars in your hosting platform and Convex production env.
Deploy app and Convex functions from the same commit SHA.
Run smoke tests immediately after deploy.
Keep rollback-ready previous deployment for fast recovery.

Important

Version skew between app code and Convex function schema is a common source of runtime bugs. Deploy them together.