Prerequisites

Before you begin, ensure your system meets these requirements:

Linux (Ubuntu 20.04+, Debian 11+, Fedora 36+, or similar)
Node.js 18+ (Node.js 22 recommended)
At least 500MB free disk space
Terminal access

💡 Tip: If you don’t have Node.js installed, follow the steps below for your distribution.

Step 1: Install Node.js

Skip this step if you already have Node.js 18 or later installed.

Ubuntu / Debian

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

Fedora

# Install Node.js using dnf
sudo dnf install nodejs npm

Arch Linux

sudo pacman -S nodejs npm

Using nvm (All Distributions)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal, then install Node.js
nvm install 22
nvm use 22

Verify Installation

node --version
# Should display v18.x.x or higher

Step 2: Install Moltbot

Run the following command in your terminal:

npm install -g moltbot

If you encounter permission errors, you have two options:

Option A: Use sudo (Quick)

sudo npm install -g moltbot

Option B: Configure npm for User Installs (Recommended)

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g moltbot

Verify the installation:

moltbot --version

Step 3: Run the Setup Wizard

Launch the interactive setup wizard:

moltbot onboard

The wizard will guide you through:

AI Provider Setup — Choose Claude, GPT-4, or another model
API Key Configuration — Enter your API key
Messaging Channels — Connect WhatsApp, Telegram, etc.

Step 4: Start the Gateway

After configuration, start the Moltbot gateway:

moltbot gateway

Expected output:

🦞 Moltbot Gateway v2026.1.24
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Gateway running on localhost:18789
✓ WebChat available at http://localhost:18789

Running as a Service (Optional)

To run Moltbot in the background and start it automatically on boot:

Using systemd

Create a service file:

sudo nano /etc/systemd/system/moltbot.service

Add the following content (replace YOUR_USERNAME):

[Unit]
Description=Moltbot Gateway
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/usr/bin/moltbot gateway
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable moltbot
sudo systemctl start moltbot

Check status:

sudo systemctl status moltbot

Next Steps

Moltbot is now installed on Linux! Continue with:

Connect WhatsApp — Add AI to your WhatsApp chats
Connect Telegram — Create a Telegram bot
Configure AI Providers — Switch or add AI models

Troubleshooting

Command Not Found After Install

If moltbot command is not found after installation:

# Check where npm installed it
npm list -g --depth=0

# Add npm global bin to PATH if needed
export PATH="$(npm config get prefix)/bin:$PATH"

Permission Denied Errors

Don’t use sudo with npm if possible. Instead, configure npm to use a user directory (see Step 2, Option B).

Port Already in Use

If port 18789 is already in use:

# Find what's using the port
sudo lsof -i :18789

# Or start Moltbot on a different port
moltbot gateway --port 18790