> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osschat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Run OpenChat locally with Bun, Convex, and GitHub OAuth.

# Quickstart

This guide gets OpenChat running locally for development and feature testing.

<Note>
  Prefer the hosted app? Use `https://osschat.dev`.
</Note>

<img className="rounded-xl" src="https://mintcdn.com/osschat/0XVzE_uVrSJzBV70/images/openchat/landing/osschat-signin-page-dark.png?fit=max&auto=format&n=0XVzE_uVrSJzBV70&q=85&s=8ffb365fb475f188de3d980df81dbeae" alt="OpenChat sign-in screen in dark mode for OAuth setup" width="1600" height="1000" data-path="images/openchat/landing/osschat-signin-page-dark.png" />

## Prerequisites

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

## Install and Run

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/opencoredev/openchat.git
    cd openchat
    bun install
    ```
  </Step>

  <Step title="Copy environment files">
    ```bash theme={null}
    cp env.web.example apps/web/.env.local
    cp env.server.example apps/server/.env.local
    ```
  </Step>

  <Step title="Set required env vars">
    In `apps/web/.env.local`, configure at least:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Configure GitHub OAuth">
    Use callback URL:

    ```
    http://localhost:3211/api/auth/callback/github
    ```
  </Step>

  <Step title="Start dev services">
    ```bash theme={null}
    bun dev
    ```

    This starts web + Convex.

    <img className="rounded-xl" src="https://mintcdn.com/osschat/0XVzE_uVrSJzBV70/images/openchat/getting-started/quickstart-home-full-dark.png?fit=max&auto=format&n=0XVzE_uVrSJzBV70&q=85&s=36c91ddc7a23065aaa3da51a8ea66de3" alt="OpenChat app shell in dark mode after local services start" width="1600" height="1000" data-path="images/openchat/getting-started/quickstart-home-full-dark.png" />
  </Step>
</Steps>

## Visual checkpoints

1. Open `http://localhost:3000`; you should see the sign-in screen.

<img className="rounded-xl" src="https://mintcdn.com/osschat/0XVzE_uVrSJzBV70/images/openchat/landing/osschat-signin-page-dark.png?fit=max&auto=format&n=0XVzE_uVrSJzBV70&q=85&s=8ffb365fb475f188de3d980df81dbeae" alt="Expected dark-mode sign-in screen after opening the app" width="1600" height="1000" data-path="images/openchat/landing/osschat-signin-page-dark.png" />

2. Sign in with GitHub; then the main app shell appears.

<img className="rounded-xl" src="https://mintcdn.com/osschat/0XVzE_uVrSJzBV70/images/openchat/getting-started/quickstart-home-full-dark.png?fit=max&auto=format&n=0XVzE_uVrSJzBV70&q=85&s=36c91ddc7a23065aaa3da51a8ea66de3" alt="Main OpenChat dark-mode UI with chat sidebar and input" width="1600" height="1000" data-path="images/openchat/getting-started/quickstart-home-full-dark.png" />

3. Start a chat and send one prompt.
4. 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

| Command           | Purpose            |
| ----------------- | ------------------ |
| `bun dev`         | Start web + Convex |
| `bun dev:web`     | Start web app only |
| `bun dev:server`  | Start Convex only  |
| `bun check`       | Lint checks        |
| `bun check-types` | Type checks        |
| `bun test`        | Test suite         |

## Next Docs

<CardGroup cols={3}>
  <Card title="Architecture" icon="sitemap" href="/guides/architecture">
    Understand the full system structure
  </Card>

  <Card title="Chat Experience" icon="message" href="/features/chat-experience">
    Learn streaming, editing, retry, and fork flows
  </Card>

  <Card title="Self-Hosting" icon="server" href="/self-hosting/docker">
    Continue with Docker or Vercel deployment
  </Card>
</CardGroup>