Self-Extensible AI Assistant 🐋

Built for folks who want their AI to actually do things — not just chat.

🚧 Active Development — This project is being actively built. Expect frequent updates!
🌐 OpenWhale Website — Coming soon
☁️ OpenWhale Hosting — Managed hosting coming soon

📋 View Full Features List

OpenWhale is an AI assistant that can take action. It connects to multiple AI models, talks on your behalf through WhatsApp/Telegram/Discord, browses the web, executes code, manages your calendar, and basically does whatever you need it to do.

Think of it as Claude, GPT-4, or DeepSeek with arms and legs.

• It's agentic — not just a chatbot. It can use tools, run commands, send messages, and interact with the real world.
• Use any model — Claude, GPT-4, DeepSeek, Groq, Gemini, Ollama. Switch whenever you want.
• Runs anywhere — Docker, bare metal, your Raspberry Pi. Whatever works for you.
• Actually secure — JWT auth, API keys, rate limiting, audit logs. The boring stuff that matters.

• Node.js 22+ — Required for the runtime
• pnpm — Recommended package manager (handles native modules better)

# Install pnpm if you don't have it
npm install -g pnpm

# Clone it
git clone https://github.com/viralcode/openwhale.git
cd openwhale

# Install dependencies (use pnpm, not npm!)
pnpm install

# Allow native modules to build (important!)
pnpm approve-builds

# Set up your environment
cp .env.example .env
# Add your API keys to .env

# Run it
pnpm run dev

docker-compose up -d

That's it. Hit http://localhost:18789/health to make sure it's alive.

Error: Could not locate the bindings file.

This happens when using npm instead of pnpm, or when native modules weren't built properly.

Fix:

# Remove existing node_modules
rm -rf node_modules package-lock.json

# Use pnpm instead
pnpm install
pnpm approve-builds   # Select all packages when prompted
pnpm run dev

Make sure you pulled the latest version of the repository which includes the lockfile:

git pull origin main

Some packages require Xcode Command Line Tools:

xcode-select --install

OpenWhale comes with a web dashboard for managing everything without touching the terminal.

Access it at: http://localhost:18789/dashboard

• Chat — Talk to the AI with full tool support
• Connect channels — Link WhatsApp, Telegram, Discord by scanning QR codes or adding tokens
• Manage providers — Add API keys for Claude, GPT-4, Gemini, etc.
• Configure skills — Enable GitHub, Notion, Weather, Google services
• View message history — See all conversations across channels
• Monitor system — Check connected channels, active sessions, audit logs

First time running? The dashboard walks you through:

1. Checking prerequisites (Node, Python, FFmpeg)
2. Adding your AI provider keys
3. Connecting messaging channels
4. Enabling skills

The dashboard is protected by authentication.

Default credentials:

Username: admin
Password: admin

⚠️ Security Note: Change the default password after first login!

Features:

• Session-based auth with 7-day expiry
• Admin can create additional users
• Password change in Settings
• Logout button in sidebar

OpenWhale can send and receive messages through multiple platforms. Here's how to set them up:

The easiest one — works with your personal WhatsApp account.

Via Dashboard:

1. Go to http://localhost:18789/dashboard
2. Navigate to Channels → WhatsApp
3. Click "Connect"
4. Scan the QR code with your phone (WhatsApp → Linked Devices → Link a Device)
5. Done! Messages to your number will be handled by the AI

Via CLI:

npm run cli whatsapp login    # Shows QR code in terminal
npm run cli whatsapp status   # Check if connected
npm run cli whatsapp logout   # Disconnect

Your session is saved in ~/.openwhale/whatsapp-auth/ so you don't need to scan again.

1. Create a bot with @BotFather on Telegram
2. Copy the bot token
3. Add to .env:

   TELEGRAM_BOT_TOKEN=your-bot-token

4. Restart OpenWhale
5. Message your bot — the AI will respond

1. Create a bot at Discord Developer Portal
2. Enable "Message Content Intent" under Bot settings
3. Copy the bot token
4. Add to .env:

   DISCORD_BOT_TOKEN=your-bot-token

5. Invite bot to your server using the OAuth2 URL generator
6. Restart OpenWhale

These are the built-in capabilities the AI can use. You don't need to configure anything — they just work.

OpenWhale has a powerful memory system (inspired by OpenClaw) that remembers context across conversations and restarts.

~/.openwhale/memory/
├── MEMORY.md           # Long-term facts
├── 2024-01-15.md       # Daily notes  
└── vector.db           # Vector embeddings for semantic search

OpenWhale supports semantic search over your memories — find related content by meaning, not just keywords.

Three embedding providers (just like OpenClaw):

1. Local (no API key!) — Uses node-llama-cpp with a 300MB GGUF model

   • Downloads automatically on first use
   • Runs entirely on your machine
   • Model: embeddinggemma-300M-Q8_0

2. OpenAI — If OPENAI_API_KEY is set

   • Model: text-embedding-3-small
   • Best accuracy, requires API key

3. Gemini — If GOOGLE_API_KEY is set

   • Model: text-embedding-004
   • Good free alternative

Auto-selection order: Local → OpenAI → Gemini

Ask the AI to:

• "Remember that my favorite color is blue" → Saves to MEMORY.md
• "Add to today's notes: meeting at 3pm" → Saves to daily log
• "Search my memory for project ideas" → Vector search
• "Index my memory files" → Re-index for search
• "Show memory status" → See embedding provider info

Conversations are saved to JSONL transcripts, so you can:

• Continue where you left off after restarts
• Keep context across multiple messages
• Review past conversations

OpenWhale can extend itself! Create custom automations via chat that persist and run on schedules.

Extensions are stored as TypeScript files in ~/.openwhale/extensions/

Just ask the AI:

• "Create an extension that reminds me to drink water every hour"
• "Make an extension that checks Bitcoin price at 9 AM and sends it to WhatsApp"
• "Create a daily standup reminder extension"

Each extension has:

{
  "name": "daily_reminder",
  "description": "Sends a daily reminder",
  "version": "1.0.0",
  "enabled": true,
  "schedule": "0 9 * * *",
  "channels": ["whatsapp"]
}

Use cron expressions for scheduled execution:

• 0 9 * * * — Daily at 9 AM
• 0 */2 * * * — Every 2 hours
• 0 9 * * 1-5 — Weekdays at 9 AM

// Extension code (runs daily)
const response = await fetch('https://api.coinbase.com/v2/prices/BTC-USD/spot');
const data = await response.json();
return `Bitcoin price: $${data.data.amount}`;

Extensions automatically send their return value to configured channels!

Skills are integrations with external services. They need API keys to work.

Access repositories, issues, pull requests.

GITHUB_TOKEN=ghp_your_token

Create a token at github.com/settings/tokens with repo scope.

Current conditions and forecasts.

OPENWEATHERMAP_API_KEY=your_key

Get a free key at openweathermap.org.

Manage pages and databases.

NOTION_API_KEY=secret_your_key

Create an integration at notion.so/my-integrations.

Calendar, Gmail, Drive, and Tasks — all in one.

1. Create a project in Google Cloud Console
2. Enable Calendar, Gmail, Drive, and Tasks APIs
3. Create OAuth credentials (Desktop app)
4. Download credentials.json to ~/.openwhale/google/credentials.json
5. Run OpenWhale and visit the Google auth URL shown in logs
6. Authorize access — tokens are saved automatically

Securely fetch passwords and secrets.

OP_CONNECT_TOKEN=your_connect_token
OP_CONNECT_HOST=http://localhost:8080

Requires 1Password Connect server.

Works automatically on Mac — no config needed. The AI can read/write your Notes and Reminders.

Control playback, search music, manage playlists.

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

Create an app at developer.spotify.com.

Manage boards, lists, and cards.

TRELLO_API_KEY=your_key
TRELLO_TOKEN=your_token

Get keys at trello.com/app-key.

OpenWhale supports 8 AI providers with automatic failover. Add the keys for whichever services you want to use.

# Example .env configuration
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
DASHSCOPE_API_KEY=...  # or QWEN_API_KEY
DEEPSEEK_API_KEY=...
GROQ_API_KEY=...
OLLAMA_HOST=http://localhost:11434

Fallback Order: Anthropic → OpenAI → Google → Qwen → DeepSeek → Groq → Together → Ollama

Switch models on the fly in the dashboard or CLI.

The CLI is where the magic happens:

# Start an interactive chat
npm run chat

# Check your setup
npm run cli providers  # See which AI providers are connected
npm run cli tools      # List available tools
npm run cli channels   # Check messaging channels
npm run cli skills     # See skill status

# WhatsApp management
npm run cli whatsapp login   # Scan QR code
npm run cli whatsapp status  # Check connection
npm run cli whatsapp logout  # Disconnect

# Background daemon (keeps running after terminal closes)
npm run cli daemon install   # Install as system service
npm run cli daemon start     # Start daemon
npm run cli daemon status    # Check if running
npm run cli daemon stop      # Stop daemon

OpenWhale exposes an OpenAI-compatible API, so you can plug it into existing tools:

# Chat completion
curl -X POST http://localhost:18789/api/agent/chat/completions \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

src/
├── agents/      # Multi-agent routing and orchestration
├── auth/        # JWT, API keys, sessions
├── channels/    # WhatsApp, Telegram, Discord, Slack adapters
├── cli.ts       # Interactive terminal interface
├── daemon/      # Background service (launchd on macOS)
├── dashboard/   # Web admin panel
├── db/          # SQLite/PostgreSQL with Drizzle ORM
├── gateway/     # Hono-based HTTP API
├── integrations/# Google APIs (Calendar, Gmail, Drive, Tasks)
├── providers/   # Anthropic, OpenAI, Google, Groq, Ollama
├── security/    # Rate limiting, RBAC, audit logs, sandboxing
├── sessions/    # Persistent conversation history
├── skills/      # GitHub, Notion, Spotify, Weather, Apple, etc.
└── tools/       # File, browser, code execution, screenshots

All settings go in .env:

# Server
GATEWAY_PORT=18789
GATEWAY_HOST=0.0.0.0

# Database (SQLite by default)
DATABASE_URL=file:./data/openwhale.db
# Or PostgreSQL:
# DATABASE_URL=postgresql://user:pass@localhost:5432/openwhale

# Security — CHANGE THIS!
JWT_SECRET=change-me-to-something-random-at-least-32-chars
SECURITY_MODE=local  # or 'strict' for production

# Logging
LOG_LEVEL=info

PRs welcome! If you find a bug or have an idea, open an issue. Keep it friendly.

MIT — do whatever you want with it.

Built with ❤️ by Jijo John