Quick Start 🚀

Get Halawi AI running locally or with Docker.

You need one AI Provider API Key (OpenAI, Claude, Gemini, etc.), a database, and the config from .env. See Getting Started below.

---

Halawi AI - An AI chatbot for individuals and teams, inspired by ChatGPT, Claude, Grok, and Gemini.

• Multi-AI Support - Integrates all major LLMs: OpenAI, Anthropic, Google, xAI, Ollama, and more
• Powerful Tools - MCP protocol, web search, JS/Python code execution, data visualization
• Image Generation - Create and edit images with AI models (OpenAI, Google Gemini, xAI)
• Automation - Custom agents, visual workflows, artifact generation
• Collaboration - Share agents, workflows, and MCP configurations with your team
• Voice Assistant - Realtime voice chat with full MCP tool integration
• Intuitive UX - Instantly invoke any feature with @mention

Built with Vercel AI SDK and Next.js, combining the best features of leading AI services into one platform.

Table of Contents

• Table of Contents
• Preview
  • 🧩 Browser Automation with Playwright MCP
  • 🔗 Visual Workflows as Custom Tools
  • 🤖 Custom Agents
  • 🎙️ Realtime Voice Assistant + MCP Tools
  • ⚡️ Quick Tool Mentions (@) & Presets
  • 🧭 Tool Choice Mode
  • 🛠️ Default Tools
    • 🌐 Web Search
    • ⚡️ JS,PYTHON Executor
    • 📊 Data Visualization Tools
• Getting Started
  • Quick Start (Docker Compose Version) 🐳
  • Quick Start (Local Version) 🚀
  • Environment Variables
• 📘 Guides
  • 🔌 MCP Server Setup & Tool Testing
  • 🐳 Docker Hosting Guide
  • 🗂️ File Storage Drivers
  • 🎯 System Prompts & Chat Customization
  • 🔐 OAuth Sign-In Setup
  • 🕵🏿 Adding openAI like providers
  • 🧪 E2E Testing Guide
• 💡 Tips
  • 💬 Temporary Chat Windows
• 🗺️ Roadmap
• 🙌 Contributing

Halawi AI is evolving at lightning speed! ⚡️ We're constantly shipping new features and smashing bugs. Star this repo to stay in the loop.

Preview

Get a feel for the UX — here's a quick look at what's possible.

🧩 Browser Automation with Playwright MCP

Example: Control a web browser using Microsoft's playwright-mcp tool.

• The LLM autonomously decides how to use tools from the MCP server, calling them multiple times to complete a multi-step task and return a final message.

Sample prompt:

1. Use the @tool('web-search') to look up information about “modelcontetprotocol.”

2. Then, using : @mcp("playwright")
   - navigate Google (https://www.google.com)
   - Click the “Login” button
   - Enter my email address (neo.cgoing@gmail.com)
   - Clock the "Next"  button
   - Close the browser

🔗 Visual Workflows as Custom Tools

Example: Create custom workflows that become callable tools in your chat conversations.

• Build visual workflows by connecting LLM nodes (for AI reasoning) and Tool nodes (for MCP tool execution)
• Publish workflows to make them available as @workflow_name tools in chat
• Chain complex multi-step processes into reusable, automated sequences

🤖 Custom Agents

Example: Create specialized AI agents with custom instructions and tool access.

• Define custom agents with specific system prompts and available tools
• Easily invoke agents in chat using @agent_name
• Build task-specific assistants like a GitHub Manager agent with issue/PR tools and project context

For instance, create a GitHub Manager agent by:

• Providing GitHub tools (issue/PR creation, comments, queries)
• Adding project details to the system prompt
• Calling it with @github_manager to manage your repository

🎙️ Realtime Voice Assistant + MCP Tools

Realtime voice-based assistant built with OpenAI's Realtime API and full MCP tool integration. Talk to the assistant naturally and it can execute tools in real time.

⚡️ Quick Tool Mentions (@) & Presets

Quickly call tool during chat by typing @toolname. No need to memorize — just type @ and pick from the list!

Tool Selection vs. Mentions (@) — When to Use What:

• Tool Selection: Make frequently used tools always available to the LLM across all chats. Great for convenience and maintaining consistent context over time.
• Mentions (@): Temporarily bind only the mentioned tools for that specific response. Since only the mentioned tools are sent to the LLM, this saves tokens and can improve speed and accuracy.

Each method has its own strengths — use them together to balance efficiency and performance.

You can also create tool presets by selecting only the MCP servers or tools you need. Switch between presets instantly with a click — perfect for organizing tools by task or workflow.

🧭 Tool Choice Mode

Control how tools are used in each chat with Tool Choice Mode — switch anytime with ⌘P.

• Auto: The model automatically calls tools when needed.
• Manual: The model will ask for your permission before calling a tool.
• None: Tool usage is disabled completely.

This lets you flexibly choose between autonomous, guided, or tool-free interaction depending on the situation.

🛠️ Default Tools

🌐 Web Search

Built-in web search powered by Tavily AI. Search the web with semantic AI optimized for AI applications and extract content from URLs directly in your chats.

• Optional: Add TAVILY_API_KEY to .env to enable web search
• Free Tier: Generous free tier available for development
• Easy Setup: Get your API key instantly at tavily.com

🎨 Image Generation

Built-in image generation and editing capabilities powered by AI models. Create, edit, and modify images directly in your chats.

• Supported Operations: Image generation, editing, and composition
• Current Models: Gemini Nano Banana, OpenAI

⚡️ JS,PYTHON Executor

Simple JS and Python execution in chat.

📊 Data Visualization Tools

Interactive Tables: Create feature-rich data tables with advanced functionality:

• Sorting & Filtering: Sort by any column, filter data in real-time
• Search & Highlighting: Global search with automatic text highlighting
• Export Options: Export to CSV or Excel format with lazy-loaded libraries
• Column Management: Show/hide columns with visibility controls
• Pagination: Handle large datasets with built-in pagination
• Data Type Support: Proper formatting for strings, numbers, dates, and booleans

Chart Generation: Visualize data with various chart types (bar, line, pie charts)

Additionally, many other tools are provided, such as an HTTP client for API requests and more.

…and there's even more waiting for you. Try it out and see what else it can do!

Getting Started

This project uses pnpm as the recommended package manager.

# If you don't have pnpm:
npm install -g pnpm

Quick Start (Docker Compose Version) 🐳

# 1. Install dependencies
pnpm i

# 2. Enter only the LLM PROVIDER API key(s) you want to use in the .env file at the project root.
# Example: The app works with just OPENAI_API_KEY filled in.
# (The .env file is automatically created when you run pnpm i.)

# 3. Build and start all services (including PostgreSQL) with Docker Compose
pnpm docker-compose:up

Quick Start (Local Version) 🚀

pnpm i

#(Optional) Start a local PostgreSQL instance
# If you already have your own PostgreSQL running, you can skip this step.
# In that case, make sure to update the PostgreSQL URL in your .env file.
pnpm docker:pg

# Enter required information in the .env file
# The .env file is created automatically. Just fill in the required values.
# For the fastest setup, provide at least one LLM provider's API key (e.g., OPENAI_API_KEY, CLAUDE_API_KEY, GEMINI_API_KEY, etc.) and the PostgreSQL URL you want to use.

pnpm build:local && pnpm start

# (Recommended for most cases. Ensures correct cookie settings.)
# For development mode with hot-reloading and debugging, you can use:
# pnpm dev

Alternative: Use Docker Compose for DB only (run app via pnpm)

# Start Postgres only via compose
# Ensure your .env includes: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB matching POSTGRES_URL
docker compose -f docker/compose.yml up -d postgres

# Apply migrations
pnpm db:migrate


# Run app locally
pnpm dev   # or: pnpm build && pnpm start

Open http://localhost:3000 in your browser to get started.

Environment Variables

The pnpm i command generates a .env file. Add your API keys there.

# === LLM Provider API Keys ===
# You only need to enter the keys for the providers you plan to use
GOOGLE_GENERATIVE_AI_API_KEY=****
OPENAI_API_KEY=****
XAI_API_KEY=****
ANTHROPIC_API_KEY=****
OPENROUTER_API_KEY=****
OLLAMA_BASE_URL=http://localhost:11434/api



# Secret for Better Auth (generate with: npx @better-auth/cli@latest secret)
BETTER_AUTH_SECRET=****

# (Optional)
# URL for Better Auth (the URL you access the app from)
BETTER_AUTH_URL=

# === Database ===
# If you don't have PostgreSQL running locally, start it with: pnpm docker:pg
POSTGRES_URL=postgres://your_username:your_password@localhost:5432/your_database_name

# (Optional)
# === Tools ===
# Tavily AI for web search and content extraction (optional, but recommended for @web and research features)
TAVILY_API_KEY=your_tavily_api_key_here


# Whether to use file-based MCP config (default: false)
FILE_BASED_MCP_CONFIG=false

# === File Storage ===
# Vercel Blob is the default storage driver (works in both local dev and production)
# Pull the token locally with `vercel env pull`
FILE_STORAGE_TYPE=vercel-blob
FILE_STORAGE_PREFIX=uploads
BLOB_READ_WRITE_TOKEN=

# -- S3 (coming soon) --
# FILE_STORAGE_TYPE=s3
# FILE_STORAGE_PREFIX=uploads
# FILE_STORAGE_S3_BUCKET=
# FILE_STORAGE_S3_REGION=

# (Optional)
# === OAuth Settings (Microsoft only) ===
# Fill in these values to enable Microsoft login

# Microsoft
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
# Optional Tenant Id
MICROSOFT_TENANT_ID=
# Set to 1 to force account selection
MICROSOFT_FORCE_ACCOUNT_SELECTION=

# Set this to 1 to disable user sign-ups.
DISABLE_SIGN_UP=

# Set this to 1 to disallow adding MCP servers.
NOT_ALLOW_ADD_MCP_SERVERS=

📘 Guides

Step-by-step setup guides for running and configuring Halawi AI.

🔌 MCP Server Setup & Tool Testing

• How to add and configure MCP servers in your environment

🐳 Docker Hosting Guide

• How to self-host Halawi AI using Docker, including environment configuration.

🗂️ File Storage Drivers

• Cloud-based file storage with Vercel Blob (default) for seamless uploads in both development and production. S3 support coming soon.

🎯 System Prompts & Chat Customization

• Personalize your Halawi AI experience with custom system prompts, user preferences, and MCP tool instructions

🔐 OAuth Sign-In Setup

• Configure Google, GitHub, and Microsoft OAuth for secure user login support.

🕵🏿 Adding openAI like providers

• Adding openAI like ai providers

🧪 E2E Testing Guide

• Comprehensive end-to-end testing with Playwright including multi-user scenarios, agent visibility testing, and CI/CD integration
  

💡 Tips

💬 Temporary Chat Windows

• Open lightweight popup chats for quick side questions or testing — separate from your main thread.

🗺️ Roadmap

Planned features coming soon to Halawi AI:

• File Upload & Storage (Vercel Blob integration)
• Image Generation
• Collaborative Document Editing (like OpenAI Canvas: user & assistant co-editing)
• RAG (Retrieval-Augmented Generation)
• Web-based Compute (with WebContainers integration)

💡 If you have suggestions or need specific features, please create an issue!

💖 Support

If this project has been helpful to you, please consider supporting its development:

• ⭐ Star this repository
• 🐛 Report bugs and suggest features

Your support helps maintain and improve this project. Thank you! 🙏

🙌 Contributing

We welcome all contributions! Bug reports, feature ideas, code improvements — everything helps us build the best local AI assistant.

⚠️ Please read our Contributing Guide before submitting any Pull Requests or Issues. This helps us work together more effectively and saves time for everyone.

For detailed contribution guidelines, please see our Contributing Guide.

Language Translations: Help us make Halawi AI accessible to more users by adding new language translations. See language.md for instructions on how to contribute translations.

Let's build it together 🚀