Skip to main content

​
Quickstart

This guide gets OpenChat running locally for development and feature testing.
Prefer the hosted app? Use https://osschat.dev.
OpenChat sign-in screen in dark mode for OAuth setup

​
Prerequisites

  • Bun 1.3+
  • Node.js 20+
  • Git
  • GitHub OAuth app credentials

​
Install and Run

1

Clone and install

git clone https://github.com/opencoredev/openchat.git
cd openchat
bun install
2

Copy environment files

cp env.web.example apps/web/.env.local
cp env.server.example apps/server/.env.local
3

Set required env vars

In apps/web/.env.local, configure at least:
VITE_CONVEX_URL=http://localhost:3210
VITE_CONVEX_SITE_URL=http://localhost:3211
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
BETTER_AUTH_SECRET=your_32_char_secret
OPENROUTER_ENCRYPTION_KEY=your_base64_32_byte_key
4

Configure GitHub OAuth

Use callback URL:
http://localhost:3211/api/auth/callback/github
5

Start dev services

bun dev
This starts web + Convex.OpenChat app shell in dark mode after local services start

​
Visual checkpoints

  1. Open http://localhost:3000; you should see the sign-in screen.
Expected dark-mode sign-in screen after opening the app
  1. Sign in with GitHub; then the main app shell appears.
Main OpenChat dark-mode UI with chat sidebar and input
  1. Start a chat and send one prompt.
  2. Open Settings and confirm Providers/Models tabs load.

​
Verify Setup

Use this for a quick functional check after the steps above:
  • Confirm bun dev shows no runtime errors in console
  • Confirm .env.local changes persist without restart prompts
  • Confirm models and providers load from the UI

​
Useful Commands

CommandPurpose
bun devStart web + Convex
bun dev:webStart web app only
bun dev:serverStart Convex only
bun checkLint checks
bun check-typesType checks
bun testTest suite

​
Next Docs

Architecture

Understand the full system structure

Chat Experience

Learn streaming, editing, retry, and fork flows

Self-Hosting

Continue with Docker or Vercel deployment