Quickstart

Prerequisites

Node.js 22+
pnpm 9+
PostgreSQL database (local for dev, or a Neon project)
OpenAI API key
Slack workspace (for bot features)

1. Clone and Install

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:

cp .env.example apps/web-app/.env.local

The minimum required variables:

# 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

Use 127.0.0.1 instead of localhost in redirect URIs. WorkOS requires this for local development.

3. Set Up Database

# Create the database
createdb whilst

# Run migrations
pnpm db:migrate

4. Build and Run

# 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

Visit the signup page

Go to http://127.0.0.1:3000/auth/signup and create a workspace.

Complete WorkOS verification

Follow the email verification flow through WorkOS.

Explore the dashboard

After verification, you’ll land on the workspace dashboard where you can create and manage documents.

Common Issues

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.

Database connection error

Verify PostgreSQL is running with pg_isready, then test the connection:

psql $POSTGRES_URL -c "SELECT 1"

Organization creation failed

In the WorkOS Dashboard, go to Organizations and enable “Allow organization creation via API”.

Next Steps

CLI

Manage documents and folders from your terminal.

Slack Setup

Connect Whilst to your Slack workspace.

Architecture

Understand the system design.

Getting Started

Features

Guides

Development

Prerequisites

1. Clone and Install

2. Configure Environment

3. Set Up Database

4. Build and Run

5. Test the Setup

Common Issues

Next Steps

CLI

Slack Setup

Architecture

​Prerequisites

​1. Clone and Install

​2. Configure Environment

​3. Set Up Database

​4. Build and Run

​5. Test the Setup

​Common Issues

​Next Steps

CLI

Slack Setup

Architecture

Prerequisites

1. Clone and Install

2. Configure Environment

3. Set Up Database

4. Build and Run

5. Test the Setup

Common Issues

Next Steps