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

# Quickstart

> Get Whilst running locally in 5 minutes

## Prerequisites

* Node.js 22+
* pnpm 9+
* PostgreSQL database (local for dev, or a [Neon](https://neon.tech) project)
* OpenAI API key
* Slack workspace (for bot features)

## 1. Clone and Install

```bash theme={null}
git clone git@github.com:ibgoldbergs/whilst-slack-bot.git
cd whilst-slack-bot
pnpm install
```

## 2. Configure Environment

Copy the example env file and fill in your values:

```bash theme={null}
cp .env.example apps/web-app/.env.local
```

The minimum required variables:

```bash theme={null}
# WorkOS (Authentication)
WORKOS_API_KEY=sk_test_your_key_here
WORKOS_CLIENT_ID=client_your_id_here
WORKOS_REDIRECT_URI=http://127.0.0.1:3000/api/auth/workos/callback

# Session
SESSION_SECRET=your-super-secret-random-string-min-32-chars

# Database (local Postgres or Neon connection string)
POSTGRES_URL=postgresql://user:password@localhost:5432/whilst

# Application
NEXT_PUBLIC_APP_URL=http://127.0.0.1:3000

# OpenAI (for AI features)
OPENAI_API_KEY=sk-your-key-here
```

<Warning>
  Use `127.0.0.1` instead of `localhost` in redirect URIs. WorkOS requires this for local development.
</Warning>

## 3. Set Up Database

```bash theme={null}
# Create the database
createdb whilst

# Run migrations
pnpm db:migrate
```

## 4. Build and Run

```bash theme={null}
# Build all packages
pnpm build

# Start the web app dev server
pnpm --filter @whilst/web-app dev
```

The app is now running at `http://127.0.0.1:3000`.

## 5. Test the Setup

<Steps>
  <Step title="Visit the signup page">
    Go to `http://127.0.0.1:3000/auth/signup` and create a workspace.
  </Step>

  <Step title="Complete WorkOS verification">
    Follow the email verification flow through WorkOS.
  </Step>

  <Step title="Explore the dashboard">
    After verification, you'll land on the workspace dashboard where you can create and manage documents.
  </Step>
</Steps>

## Common Issues

<AccordionGroup>
  <Accordion title="Invalid redirect URI error">
    Go to **WorkOS Dashboard → Applications → Your App → Redirect URIs** and add `http://127.0.0.1:3000/api/auth/workos/callback`. Make sure to use `127.0.0.1`, not `localhost`.
  </Accordion>

  <Accordion title="Database connection error">
    Verify PostgreSQL is running with `pg_isready`, then test the connection:

    ```bash theme={null}
    psql $POSTGRES_URL -c "SELECT 1"
    ```
  </Accordion>

  <Accordion title="Organization creation failed">
    In the WorkOS Dashboard, go to **Organizations** and enable "Allow organization creation via API".
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/features/cli">
    Manage documents and folders from your terminal.
  </Card>

  <Card title="Slack Setup" icon="slack" href="/guides/slack-setup">
    Connect Whilst to your Slack workspace.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/architecture">
    Understand the system design.
  </Card>
</CardGroup>