How to Use moltbot

moltbot is an open-source, self-hosted personal AI assistant that has been described as "a true 24/7 AI employee." Unlike traditional cloud-based AI assistants, moltbot runs on your own hardware and integrates deeply with your local computing environment and daily communication tools.

The core philosophy behind moltbot is local-first and self-hosted, giving you complete control over your data, privacy, and functionality. Through its unique Gateway architecture, moltbot seamlessly embeds into popular chat platforms like WhatsApp, Telegram, Discord, and Slack, enabling a revolutionary "work in chat" experience. Discover why moltbot is trusted by 61,500+ developers worldwide.

Who Should Use This Guide?

This comprehensive guide is designed for:

• Developers looking to set up a personal AI coding assistant
• Power users who want to automate daily tasks through chat interfaces
• Teams seeking a self-hosted AI solution with full control
• Privacy-conscious users who prefer local-first AI tools

Explore real-world examples in our moltbot use cases collection.

Before installing moltbot, ensure your system meets the following requirements. The setup process is straightforward, but having the right environment is crucial for a smooth experience.

Verifying Node.js Installation

Check if Node.js is installed and verify the version:

# Check Node.js version
node --version
# Should output: v22.x.x or higher

# If not installed, use nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

moltbot offers multiple installation methods to suit different needs. The official installation script is recommended for most users as it handles all dependencies and configurations automatically.

curl -fsSL https://molt.bot/install.sh | bash

moltbot --version

wsl --install -d Ubuntu

curl -fsSL https://molt.bot/install.sh | bash

git clone https://github.com/steipete/moltbot.git
cd moltbot

./docker-setup.sh

# Build the image
docker build -t moltbot:local -f Dockerfile .

# Run onboard wizard
docker compose run --rm moltbot-cli onboard

# Start the Gateway
docker compose up -d moltbot-gateway

# Using npm
npm install -g moltbot@latest

# Using pnpm
pnpm add -g moltbot@latest

# Verify installation
moltbot --version

After installation, you'll need to configure moltbot using the interactive onboard command. This wizard guides you through all essential settings including authentication, channels, and daemon setup.

moltbot onboard --install-daemon

Configuration Options

During the onboarding process, you'll configure:

# Check Gateway status
moltbot gateway status

# Verify system health
moltbot health

# View all status information
moltbot status --all

moltbot gateway --port 18789 --verbose

Configuration File Location

moltbot stores its configuration in ~/.moltbot/moltbot.json. You can manually edit this file to customize advanced settings:

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

One of moltbot's most powerful features is its ability to integrate with multiple chat platforms. This allows you to interact with your AI assistant through familiar interfaces without switching apps.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

moltbot channels login

{
  "channels": {
    "telegram": {
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  }
}

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

{
  "channels": {
    "slack": {
      "enabled": true,
      "appToken": "xapp-...",
      "botToken": "xoxb-..."
    }
  }
}

moltbot's pairing system is a crucial security feature that prevents unauthorized access to your AI assistant. By default, the dmPolicy is set to "pairing", which requires manual approval for any new user attempting to interact with your bot.

How Pairing Works

1. A new user sends a direct message to your moltbot
2. moltbot responds with a pairing code
3. You review the request and approve it using the CLI
4. Once approved, the user can freely interact with moltbot

Managing Pairing Requests

# List pending pairing requests for a channel
moltbot pairing list whatsapp
moltbot pairing list telegram
moltbot pairing list discord

# Approve a pairing request with the provided code
moltbot pairing approve whatsapp ABC123

# List all approved users
moltbot pairing list --approved

DM Policy Options

Skills are moltbot's core extension mechanism. They allow you to define new capabilities for your AI assistant using simple Markdown files. Each skill contains instructions that guide the AI agent on how to perform specific tasks.

Understanding Skill Priority

moltbot loads skills in this priority order:

1. Workspace skills: <workspace>/skills/ (highest priority)
2. Local/hosted skills: ~/.moltbot/skills/
3. Bundled skills: Built-in skills (lowest priority)

Creating a Custom Skill

mkdir -p ~/moltbot-workspace/skills/my-custom-skill
cd ~/moltbot-workspace/skills/my-custom-skill

---
name: weather-checker
description: Check current weather for any city using a weather API.
user-invocable: true
metadata: {"moltbot":{"requires":{"env":["WEATHER_API_KEY"]}}}
---

## Instructions

When the user asks about weather:
1. Identify the city from the user's request
2. Execute: `curl "https://api.weather.com/v1/current?city={city}&key=$WEATHER_API_KEY"`
3. Parse the JSON response and present a friendly summary
4. Include temperature, conditions, and humidity

Installing Community Skills from MoltHub

MoltHub is the public skill registry where you can discover and install community-contributed skills.

# Install a skill from MoltHub
molthub install weather-forecast

# Update all installed skills
molthub update --all

# Sync local skills to MoltHub
molthub sync --all

Skill Configuration

Configure individual skills in your moltbot.json:

{
  "skills": {
    "entries": {
      "weather-checker": {
        "enabled": true,
        "apiKey": "your-weather-api-key",
        "config": {
          "defaultUnit": "celsius"
        }
      },
      "unwanted-skill": {
        "enabled": false
      }
    }
  }
}

Gating Mechanism

Use the requires field in skill metadata to ensure skills only load when their dependencies are available:

• requires.bins: Required binary executables (e.g., ["python3", "ffmpeg"])
• requires.env: Required environment variables (e.g., ["API_KEY"])

Voice Interaction

moltbot supports natural voice interaction through Voice Wake and Talk Mode, enabling hands-free operation.

Talk Mode Configuration

{
  "talk": {
    "voiceId": "elevenlabs_voice_id",
    "modelId": "eleven_v3",
    "apiKey": "your_elevenlabs_api_key",
    "interruptOnSpeech": true
  }
}

Canvas Visual Workspace

Canvas is a macOS feature that provides an agent-controlled visual workspace. It renders HTML/CSS/JS content and supports Agent-driven UI (A2UI).

# Display the Canvas panel
moltbot nodes canvas present --node <id>

# Navigate to a URL or local path
moltbot nodes canvas navigate --node <id> --url "/"

# Execute JavaScript in Canvas context
moltbot nodes canvas eval --node <id> --js "document.title = 'New Title';"

# Push A2UI content
moltbot nodes canvas a2ui push --node <id> --text "Hello from A2UI"

Automated Tasks (Cron Jobs)

Schedule automated tasks using moltbot's built-in Gateway scheduler. Supports flexible scheduling with at, every, and cron expressions.

# Add a one-time task (runs in 20 minutes)
moltbot cron add \
  --name "Reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: Check your email" \
  --wake now

# Add a daily recurring task
moltbot cron add \
  --name "Daily Summary" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Generate today's summary report" \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

# List all scheduled jobs
moltbot cron list

# Remove a scheduled job
moltbot cron remove <job-id>

moltbot's deployment strategy centers around the Gateway component. Whether running locally or in the cloud, the core principle is to keep the Gateway secure while enabling remote access through encrypted tunnels.

Local Deployment

For personal use on your own machine, local deployment offers the fastest and most straightforward experience.

# Start Gateway (daemon mode)
moltbot onboard --install-daemon

# Or start manually in foreground
moltbot gateway --port 18789

# Access locally
# Control UI: http://127.0.0.1:18789/
# WebSocket: ws://127.0.0.1:18789

Remote Access Options

ssh -N -L 18789:127.0.0.1:18789 user@remote

moltbot gateway --tailscale serve

Cloud/Container Deployment

For VPS or cloud environments, Docker Compose provides isolation and portability:

# Quick setup with Docker
./docker-setup.sh

# Or manual steps
docker build -t moltbot:local -f Dockerfile .
docker compose run --rm moltbot-cli onboard
docker compose up -d moltbot-gateway

Since moltbot has the ability to execute system commands and access local resources, security configuration is critical. The core principle is: "Access control before intelligence." For comprehensive security guidance, see our moltbot security guide.

Security Audit Tool

moltbot includes a built-in security audit command to identify and fix common vulnerabilities:

# Basic security audit
moltbot security audit

# Deep audit with Gateway probing
moltbot security audit --deep

# Auto-fix common issues
moltbot security audit --fix

Core Security Practices

Recommended Security Configuration

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-random-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "ro"
      },
      "tools": {
        "deny": ["exec", "write", "apply_patch"]
      }
    }
  }
}

"First 60 Seconds" Diagnostic Flow

When encountering issues, run these commands in order:

# 1. Check basic status
moltbot status

# 2. Full status report
moltbot status --all

# 3. Probe Gateway connectivity
moltbot gateway probe

# 4. Run health diagnostics
moltbot doctor

# 5. Watch logs in real-time
moltbot logs --follow

Common Issues and Solutions

# Find npm's global prefix
npm prefix -g

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$(npm prefix -g)/bin:$PATH"

# Reload your shell
source ~/.zshrc

Debug Mode

Enable runtime configuration overrides without modifying files:

# In chat, enable debug mode first (requires commands.debug: true)
/debug show
/debug set messages.responsePrefix="[TEST]"
/debug reset