Moltbot on macOS

Run your personal AI assistant natively on Mac. Full support for Apple Silicon and Intel, with voice wake, system integration, and always-on availability.

System Requirements

Moltbot runs natively on macOS with full support for both Apple Silicon and Intel processors.

macOS Version	macOS 12 (Monterey) or later
Architecture	Apple Silicon (M1/M2/M3/M4) or Intel x64
Node.js	v22.0.0 or later (LTS recommended)
RAM	8 GB minimum, 16 GB recommended
Storage	500 MB for base install + workspace data
Network	Internet connection for AI API calls

💡 Note: For local model support via Ollama, 16 GB RAM is recommended. Apple Silicon Macs provide excellent performance for local AI inference.

Quick Install (Recommended)

The fastest way to get started is using npm with the interactive onboarding wizard.

Step 1: Install Node.js (if needed)

Moltbot requires Node.js 22 or later. Install via Homebrew:

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js 22
brew install node@22

Step 2: Install Moltbot

Install Moltbot globally via npm:

npm install -g moltbot@latest

Step 3: Run the Onboarding Wizard

The wizard guides you through initial setup:

moltbot onboard --install-daemon

This will:

Create your workspace at ~/.moltbot/
Configure your AI provider (Claude, GPT, Gemini, etc.)
Set up the Gateway daemon service
Guide you through channel connections

Step 4: Start Chatting

Once setup is complete, you can interact via CLI or connected channels:

# Chat via command line
moltbot chat "Hello, what can you do?"

# Or open the web interface
moltbot ui

Installation Methods

Choose the method that works best for you

📦

npm (Recommended)

Global install via npm. Easiest to update and manage. Requires Node.js 22+.

🍺

Homebrew

Install via Homebrew tap. Automatic updates and dependency management.

💿

DMG Download

Standalone macOS app with bundled Node.js. No terminal required.

🛠️

From Source

Clone the repo and build locally. For developers who want to contribute.

Install via Homebrew

Homebrew provides easy installation and automatic updates for Moltbot.

# Add the Moltbot tap
brew tap moltbot/tap

# Install Moltbot
brew install moltbot

# Run onboarding
moltbot onboard --install-daemon

To update Moltbot later:

brew upgrade moltbot

DMG Download (GUI App)

The Moltbot macOS app provides a native experience with menu bar integration and automatic updates.

⬇️ Download for Apple Silicon (M1/M2/M3/M4)⬇️ Download for Intel

Installation Steps:

1.Download the DMG file for your Mac architecture
2.Open the DMG and drag Moltbot to Applications
3.Launch Moltbot from Applications or Spotlight
4.Follow the in-app setup wizard
5.Grant necessary permissions when prompted

⚠️ Gatekeeper Notice: On first launch, macOS may show "Moltbot can't be opened because it is from an unidentified developer." Right-click the app, select Open, then click Open in the dialog to bypass this.

Running as a Background Service

For always-on availability, Moltbot runs as a background daemon using macOS launchd.

# Install the daemon (if not done during onboard)
moltbot daemon install

# Start the daemon
moltbot daemon start

# Check daemon status
moltbot daemon status

# Stop the daemon
moltbot daemon stop

# View daemon logs
moltbot daemon logs

The daemon is managed via launchd at:

~/Library/LaunchAgents/net.moltai.moltbot.plist

💡 Auto-start: By default, the daemon starts automatically when you log in. To disable auto-start, run moltbot daemon disable.

Configure AI Provider

Moltbot supports multiple AI providers. Choose based on your needs for quality, speed, and cost.

🟣 Anthropic Claude (Recommended)

Best overall performance for agentic tasks. Supports Claude 3.5 Sonnet and Claude 3 Opus.

export ANTHROPIC_API_KEY="sk-ant-..."

🟢 OpenAI GPT

Supports GPT-4o, GPT-4 Turbo, and GPT-3.5. Good balance of speed and capability.

export OPENAI_API_KEY="sk-..."

🔵 Google Gemini

Supports Gemini 1.5 Pro and Flash. Excellent for long context windows.

export GOOGLE_AI_API_KEY="..."

🏠 Local Models (Ollama)

Run models locally for privacy. Supports Llama 3, Mixtral, and more.

# Install Ollama first
brew install ollama

Configure your provider in the workspace settings:

# Interactive configuration
moltbot config set model.provider anthropic
moltbot config set model.name claude-sonnet-4-20250514

# Or edit directly
vim ~/.moltbot/config.yaml

Voice Wake & Talk Mode

Moltbot supports always-on voice interaction on macOS with optional wake word detection.

🎤

Voice Input

Speak naturally to your assistant using system microphone

🔊

Voice Output

ElevenLabs integration for natural text-to-speech

👂

Wake Word

"Hey Moltbot" activation (optional)

# Enable voice mode
moltbot voice enable

# Configure ElevenLabs for TTS (optional)
export ELEVENLABS_API_KEY="..."
moltbot config set voice.tts.provider elevenlabs

# Start voice session
moltbot voice start

⚠️ Permissions Required: Voice mode requires Microphone access. Go to System Settings → Privacy & Security → Microphone and enable access for Terminal or Moltbot.app.

Connect Chat Channels

Connect Moltbot to your existing chat apps. Each channel runs as a separate bridge.

# Connect WhatsApp (scan QR code)
moltbot channel add whatsapp

# Connect Telegram (enter bot token)
moltbot channel add telegram

# Connect Slack (OAuth flow)
moltbot channel add slack

# Connect Discord (enter bot token)
moltbot channel add discord

# Connect iMessage (macOS only)
moltbot channel add imessage

# List connected channels
moltbot channel list

💡 iMessage on macOS: Moltbot can read and send iMessages directly on macOS. Requires Full Disk Access permission in System Settings → Privacy & Security → Full Disk Access.

Updating Moltbot

Keep Moltbot up to date to get the latest features and security fixes.

npm Install

npm update -g moltbot
moltbot daemon restart

Homebrew Install

brew upgrade moltbot
moltbot daemon restart

Check your current version and available updates:

# Check current version
moltbot --version

# Check for updates
moltbot update check

Troubleshooting

Common issues and solutions for macOS installation.

Run Diagnostics

The moltbot doctor command checks your setup and identifies issues:

moltbot doctor

"command not found: moltbot"

npm global binaries not in PATH. Add to your shell config:

export PATH="$PATH:$(npm config get prefix)/bin"

"Permission denied" errors

Avoid using sudo with npm. Fix npm permissions:

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Node.js version too old

Moltbot requires Node.js 22+. Update via Homebrew:

brew install node@22
brew link --overwrite node@22

Daemon won't start

Check logs and restart:

moltbot daemon logs
moltbot daemon stop
moltbot daemon start

WhatsApp QR code not showing

Ensure you're running in a terminal that supports QR codes, or use the web UI:

moltbot ui
# Then connect WhatsApp from the web interface