Skip to main content
This guide will help you set up Maxw AI on your local machine and get your first AI chat session running.

​
Prerequisites

Before you begin, ensure you have the following installed:

Bun

Package manager (v1.2.21 or later)

PostgreSQL

Database server (v14 or later)

Node.js

Required for React Native (v18 or later)
If you don’t have Bun installed, see our Installation Guide for setup instructions.

​
Quick Setup

1

Clone the repository

Clone the Maxw AI repository and navigate to the project directory:
git clone https://github.com/maxwiseman/maxw-ai-v3.git
cd maxw-ai-v3
2

Install dependencies

Install all dependencies for both web and mobile apps using Bun:
bun install
This installs dependencies for:
  • The web application (apps/web)
  • The mobile application (apps/native)
  • All shared packages
The project uses Bun’s workspace feature to manage the monorepo. All dependencies are installed from the root.
3

Set up environment variables

Create a .env file in the root directory (not in apps/web/.env):
touch .env
Add the following required environment variables:
.env
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/maxw_ai"

# Authentication
AUTH_SECRET="your-secret-key-here"  # Generate with: openssl rand -base64 32

# Upstash Search (for Canvas content)
UPSTASH_SEARCH_URL="https://your-instance.upstash.io"
UPSTASH_SEARCH_TOKEN="your-upstash-token"
NEXT_PUBLIC_UPSTASH_SEARCH_TOKEN="your-public-token"

# AI API Keys
ANTHROPIC_API_KEY="sk-ant-..."  # Required for Claude
OPENAI_API_KEY="sk-..."         # Required for embeddings
GOOGLE_GENERATIVE_AI_API_KEY="..."  # Optional
The .env file must be in the repository root, not in apps/web/. Drizzle reads from the root directory.
4

Initialize the database

Push the database schema to your PostgreSQL instance:
bun db:push
This command:
  • Connects to your PostgreSQL database using DATABASE_URL
  • Creates all necessary tables (users, sessions, todos, study sets, memory)
  • Sets up foreign key relationships
You can explore your database schema using Drizzle Studio:
bun db:studio
This opens a visual database browser at http://localhost:4983.
5

Start the development servers

Start the web application:
bun dev
The web app will be available at http://localhost:3000.For mobile development, the Expo dev server will start and you can:
  • Scan the QR code with the Expo Go app (iOS/Android)
  • Press i for iOS simulator
  • Press a for Android emulator
6

Create your first account

Navigate to http://localhost:3000 in your browser:
  1. Click Sign Up to create a new account
  2. Enter your name, email, and password
  3. Verify your email (if email verification is enabled)
  4. You’ll be redirected to the dashboard
The first user you create will have access to all features. You can add Canvas LMS credentials in your account settings.
7

Start your first AI chat

Once logged in:
  1. Click New Chat or navigate to the chat interface
  2. Try asking the AI assistant questions like:
    • “What can you help me with?”
    • “Search for information about photosynthesis”
    • “Calculate the derivative of x^2 + 3x”
  3. Explore the AI’s capabilities including web search, code execution, and memory
The AI assistant has access to:
  • Web search for current information
  • Code execution for calculations and analysis
  • Memory to remember your preferences
  • Canvas integration (once you connect your account)
  • Todo management and study set creation

​
Verification

To verify your setup is working correctly:
Visit http://localhost:3000 and ensure:
  • The page loads without errors
  • You can create an account
  • The AI chat interface is accessible
Run this command to open Drizzle Studio:
bun db:studio
You should see your database tables and the user you created.
Send a message to the AI assistant. You should see:
  • Streaming responses (words appear one by one)
  • The AI can use tools (try asking it to search the web)
  • Responses are relevant and contextual

​
Next Steps

Now that you have Maxw AI running, explore these features:

Connect Canvas LMS

Import your courses and assignments

Explore AI Features

Learn about all AI capabilities

Manage Tasks

Create and organize your todos

Create Study Sets

Generate flashcards for studying

​
Troubleshooting

If you see database connection errors:
  1. Verify PostgreSQL is running: pg_isready
  2. Check your DATABASE_URL format: postgresql://user:password@host:port/database
  3. Ensure the database exists: createdb maxw_ai
  4. Verify credentials are correct
If bun is not recognized:
  1. Install Bun: curl -fsSL https://bun.sh/install | bash
  2. Restart your terminal
  3. Verify installation: bun --version
If the AI chat doesn’t respond:
  1. Check your ANTHROPIC_API_KEY is valid
  2. Verify you have API credits remaining
  3. Check browser console for errors (F12)
  4. Check server logs for detailed error messages
If port 3000 is already in use:
  1. Kill the process using port 3000: lsof -ti:3000 | xargs kill -9
  2. Or specify a different port: PORT=3001 bun dev:web
For detailed installation instructions and production setup, see our Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us