Skip to main content
This guide will help you set up and run the Vercel AI Chatbot on your local machine. You’ll go from zero to a fully functional chatbot with database persistence in just a few steps.

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18.x or higher installed
  • pnpm 9.x or higher (specified in package.json: [email protected])
  • A Vercel account (for AI Gateway, Blob storage, and Postgres)
  • Git installed on your machine
The chatbot uses pnpm as its package manager. While you can use npm or yarn, pnpm is recommended for consistency with the project configuration.

​
Get started in 5 steps

1

Clone the repository

Clone the chatbot repository to your local machine:
git clone https://github.com/vercel/openchat.git
cd openchat
This downloads the complete chatbot template including all source code, configuration files, and database schemas.
2

Install dependencies

Install all required packages using pnpm:
pnpm install
This installs:
  • Next.js 16 - React framework with App Router
  • AI SDK 6.0 - Vercel’s AI toolkit for LLM integration
  • Drizzle ORM - TypeScript ORM for database operations
  • Auth.js - Authentication framework
  • shadcn/ui - UI component library
  • And 90+ other dependencies for a complete chatbot experience
Installation typically takes 1-2 minutes depending on your internet connection.
3

Set up environment variables

Create a .env.local file in the root directory with your configuration:
cp .env.example .env.local
Open .env.local and configure the required variables:
.env.local
# Generate a random secret: https://generate-secret.vercel.app/32
AUTH_SECRET=your_random_secret_here

# AI Gateway API key (required for non-Vercel deployments)
# Get yours at: https://vercel.com/ai-gateway
AI_GATEWAY_API_KEY=your_ai_gateway_key

# Vercel Blob for file storage
# Create at: https://vercel.com/docs/vercel-blob
BLOB_READ_WRITE_TOKEN=your_blob_token

# PostgreSQL database connection
# Create at: https://vercel.com/docs/postgres
POSTGRES_URL=your_postgres_connection_string

# Redis for caching (optional)
# Create at: https://vercel.com/docs/redis
REDIS_URL=your_redis_url
Never commit your .env.local file to version control. It contains sensitive credentials that should remain private.

​
Quick setup with Vercel CLI

If you’re deploying to Vercel, you can automatically pull environment variables:
# Install Vercel CLI globally
npm i -g vercel

# Link your project to Vercel
vercel link

# Pull environment variables
vercel env pull
4

Run database migrations

Set up your database schema by running migrations:
pnpm db:migrate
This command:
  • Connects to your PostgreSQL database using POSTGRES_URL
  • Creates all required tables (users, chats, messages, documents, etc.)
  • Applies the latest schema changes from lib/db/migrations
You should see output like:
⏳ Running migrations...
✅ Migrations completed in 234 ms
If POSTGRES_URL is not defined, migrations will be skipped. This is useful for deployments where migrations run automatically.
5

Start the development server

Launch the chatbot in development mode:
pnpm dev
This starts:
  • Next.js development server with Turbopack (faster builds)
  • Hot module replacement for instant updates
  • API routes for chat, documents, and authentication
Your chatbot is now running at http://localhost:3000
The dev server uses --turbo flag for faster compilation. Your changes will appear instantly as you edit files.

​
Verify your setup

Once the server is running, test your chatbot:
  1. Open your browser to http://localhost:3000
  2. Create an account or sign in (Auth.js handles this automatically)
  3. Start chatting - Try asking “What can you help me with?”
  4. Test file uploads - Upload a document to see the artifact system in action
By default, the chatbot uses GPT-4.1 Mini via Vercel AI Gateway. You can switch to other models like Claude or Gemini in the model selector.

​
Common issues

Problem: POSTGRES_URL is not configured correctly.Solution:
  • Verify your database connection string is correct
  • Ensure your database is accessible (check firewall/network settings)
  • For Vercel Postgres, make sure you’ve created a database in your project
Problem: Missing or invalid AI_GATEWAY_API_KEY.Solution:
  • Create an API key at https://vercel.com/ai-gateway
  • For Vercel deployments, OIDC tokens are used automatically (no key needed)
  • Verify the key is correctly set in .env.local
Problem: Another process is using port 3000.Solution:
# Use a different port
PORT=3001 pnpm dev

​
Next steps

Now that your chatbot is running:

Explore features

Learn about the chat interface, artifacts, and AI tools

Add AI tools

Extend your chatbot with custom tools and capabilities

Deploy to Vercel

Deploy your chatbot to production in one click

Customize UI

Make the chatbot match your brand

​
Available scripts

Here are the key commands you’ll use during development:
CommandDescription
pnpm devStart development server with Turbopack
pnpm buildBuild for production (runs migrations first)
pnpm startStart production server
pnpm db:migrateRun database migrations
pnpm db:studioOpen Drizzle Studio to view database
pnpm db:generateGenerate new migration files
pnpm lintCheck code quality with Ultracite
pnpm formatAuto-fix formatting issues
Use pnpm db:studio to visually explore your database and see chats, messages, and user data in real-time.

Build docs developers (and LLMs) love

Get started for freeTalk to us