How to Install MoltBot

📋 Prerequisites & System Requirements

Before installing MoltBot, ensure your system meets these requirements:

Minimum Requirements

What You'll Need

• ✅ Command-line access (Terminal on Mac/Linux, PowerShell on Windows)
• ✅ Administrator/sudo privileges
• ✅ API key from at least one AI provider (Anthropic, OpenAI, or Google)
• ✅ Basic familiarity with terminal commands

⚡ Quick Installation (Universal Method)

This method works on all supported platforms once Node.js is installed:

Step 1: Install Node.js

Download Node.js v22+ from nodejs.org and install it for your platform.

Step 2: Install MoltBot

# Install MoltBot globally using npm
npm install -g MoltBot@latest

# Verify installation
MoltBot --version

Step 3: Run Onboarding Wizard

# Start the interactive setup
MoltBot onboard

The onboarding wizard will guide you through:

• Creating your workspace directory
• Configuring the Gateway
• Adding AI provider API keys
• Setting up your first messaging channel
• Installing recommended skills

🍎 macOS Installation Guide

For detailed macOS-specific instructions, see our dedicated MoltBot for Mac guide.

Using Homebrew (Recommended)

# Install Node.js via Homebrew
brew install node@22

# Install MoltBot
npm install -g MoltBot@latest

# Start onboarding
MoltBot onboard

macOS-Specific Considerations

• iMessage Integration: Requires macOS and additional setup via imsg CLI
• Permissions: You may need to grant Terminal full disk access in System Settings
• M1/M2/M3 Chips: Fully supported with native ARM builds

→ Setting up MoltBot on Mac Mini as a home server

🪟 Windows Installation Guide

MoltBot on Windows requires WSL2 (Windows Subsystem for Linux). For complete details, see MoltBot for Windows.

Step 1: Enable WSL2

# Run in PowerShell as Administrator
wsl --install

# Restart your computer
# After restart, set up Ubuntu username/password

Step 2: Install Node.js in WSL

# Inside WSL Ubuntu terminal
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version

Step 3: Install MoltBot

npm install -g MoltBot@latest
MoltBot onboard

Windows Tips

• Access Windows files from WSL at /mnt/c/
• Use Windows Terminal for better experience
• Consider running MoltBot as a background service

🐧 Linux Installation Guide

Full guide: MoltBot on Linux

Ubuntu/Debian

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install MoltBot
sudo npm install -g MoltBot@latest

# Run onboarding
MoltBot onboard

Fedora/RHEL

# Install Node.js
sudo dnf install nodejs

# Install MoltBot
sudo npm install -g MoltBot@latest
MoltBot onboard

Running as a Service (systemd)

# Create service file
sudo nano /etc/systemd/system/MoltBot.service

# Add configuration (see Linux guide for details)
sudo systemctl enable MoltBot
sudo systemctl start MoltBot

⚙️ Configuration & Setup

Adding API Keys

MoltBot needs at least one AI provider. Here's how to add keys:

# Run setup wizard
MoltBot setup --wizard

# Or manually edit credentials
nano ~/.MoltBot/credentials/default.yaml

Supported AI Providers

Learn more: MoltBot Models Comparison

Starting the Gateway

# Start MoltBot Gateway
MoltBot gateway start

# Access web UI at:
# http://localhost:18789

🔧 Troubleshooting Common Issues

Issue: "Command not found: MoltBot"

Solution:

# Check if npm global bin is in PATH
npm config get prefix

# Add to PATH (macOS/Linux)
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue: "Permission denied" during installation

Solution:

# On macOS/Linux, use sudo
sudo npm install -g MoltBot@latest

# Or configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Issue: Port 18789 already in use

Solution:

# Find process using the port
lsof -i :18789  # macOS/Linux
netstat -ano | findstr :18789  # Windows

# Kill the process or change MoltBot port in config

Issue: Node.js version too old

Solution:

# Use nvm to install Node.js 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

🎯 Next Steps After Installation

Congratulations! MoltBot is now installed. Here's what to do next:

1. Connect a Messaging Platform

• Connect to Telegram (Easiest for beginners)
• Connect to WhatsApp
• Connect to Discord

2. Install Essential Skills

Visit MoltBot Skills Guide to discover useful plugins.

3. Learn How to Use MoltBot

Read our Complete User Guide for tips and best practices.

4. Advanced Deployments

• Deploy with Docker
• Run on AWS EC2
• Set up Mac Mini as AI Server