DEV Community

Cover image for Self-Hosted AI Assistant: Complete Moltbot Installation Guide for Docker
1Richter
1Richter

Posted on • Originally published at lrichter.net

Self-Hosted AI Assistant: Complete Moltbot Installation Guide for Docker

#docker #ai #cli #tutorial

Run your own ChatGPT-like AI assistant on WhatsApp, Telegram, and Discord with complete privacy and control

Are you looking for a self-hosted AI assistant that gives you the power of ChatGPT, Claude, and Gemini without sacrificing your privacy? Moltbot is an open-source AI gateway that lets you deploy your own AI chatbot on Docker and connect it to WhatsApp, Telegram, Discord, Slack, and more.

In this comprehensive guide, I'll walk you through installing Moltbot with Docker Compose, configuring it for maximum security, and solving common issues I encountered during my own deployment.

What is Moltbot? Open-Source AI Assistant for Self-Hosting

Moltbot is a privacy-first AI assistant that runs entirely on your own infrastructure. Unlike cloud-based AI services, Moltbot gives you:

  • Complete data privacy - all conversations stay on your server
  • Multi-platform support - WhatsApp, Telegram, Discord, Slack, and more
  • Multiple AI models - Google Gemini, OpenAI GPT-4, Anthropic Claude, GitHub Copilot
  • Docker-native deployment - easy installation with Docker Compose
  • Full customization - extend with plugins, skills, and custom tools

Key Features

  • 🔒 Privacy-First: All data stays on your server - no third-party cloud services
  • 🌐 Multi-Channel: WhatsApp, Telegram, Discord, Slack, and more
  • 🤖 Multi-Model: Google Gemini, OpenAI GPT, Anthropic Claude, GitHub Copilot, and others
  • 🛠️ Extensible: Plugins for browser automation, shell access, memory, and custom tools
  • 📱 Mobile-Ready: Full AI capabilities right from your phone via WhatsApp
  • 🐳 Docker-Native: Easy deployment with Docker Compose
  • 🔐 Secure: Built-in sandboxing, approval workflows, and access controls

Why Choose Moltbot Over Cloud AI Services?

For Beginners: Easy Self-Hosted AI Setup

  • Zero AI API costs: Use free tiers (Google Gemini) or your existing GitHub Copilot subscription or ollama
  • Simple Docker installation: One docker compose up command to get started
  • WhatsApp AI integration: Talk to your AI assistant like you're texting a friend
  • Smart security defaults: Works out of the box with sensible privacy settings
  • No coding required: Configure everything through JSON files

For Advanced Users: Full Infrastructure Control

  • Shell access via chat: Execute Linux commands on your server from WhatsApp
  • Docker container management: Control containers, check logs, deploy services remotely
  • Custom skills and plugins: Extend with Python/Node.js scripts
  • Browser Automation: Headless Chromium for web scraping and testing
  • Infrastructure as Code: Manage your entire homelab via WhatsApp

How to Install Moltbot with Docker Compose (Step-by-Step)

Prerequisites for Self-Hosting Moltbot

  • Docker and Docker Compose installed
  • A Google API Key (free tier available) or GitHub Copilot subscription
  • A phone number for WhatsApp Web pairing

Quick Start

  1. Clone or create your Moltbot directory: 
mkdir ~/moltbot && cd ~/moltbot
Enter fullscreen mode Exit fullscreen mode
  1. Create a docker-compose.yml: 
services:
  moltbot-gateway:
    image: moltbot:local
    build:
      context: .
      args:
        CLAWDBOT_DOCKER_APT_PACKAGES: ${CLAWDBOT_DOCKER_APT_PACKAGES}
    user: root
    environment:
      HOME: /home/node
      TERM: xterm-256color
      CLAWDBOT_GATEWAY_TOKEN: ${CLAWDBOT_GATEWAY_TOKEN}
      MOLTBOT_STATE_DIR: /home/node/.moltbot
      CLAWDBOT_STATE_DIR: /home/node/.moltbot
      GOOGLE_GENERATIVE_AI_API_KEY: ${GOOGLE_API_KEY}
    volumes:
      - ${CLAWDBOT_CONFIG_DIR}:/home/node/.moltbot
      - ${CLAWDBOT_WORKSPACE_DIR}:/home/node/clawd
    ports:
      - "${CLAWDBOT_GATEWAY_PORT:-18789}:18789"
      - "${CLAWDBOT_BRIDGE_PORT:-18790}:18790"
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${CLAWDBOT_GATEWAY_BIND:-lan}",
        "--port",
        "${CLAWDBOT_GATEWAY_PORT:-18789}"
      ]
Enter fullscreen mode Exit fullscreen mode
  1. Create a .env file: 
CLAWDBOT_CONFIG_DIR=./config
CLAWDBOT_WORKSPACE_DIR=./workspace
CLAWDBOT_GATEWAY_PORT=18789
CLAWDBOT_BRIDGE_PORT=18790
CLAWDBOT_GATEWAY_BIND=lan
GOOGLE_API_KEY=your_google_api_key_here
Enter fullscreen mode Exit fullscreen mode
  1. Create a Dockerfile: 
FROM node:22-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

ARG CLAWDBOT_DOCKER_APT_PACKAGES=""
RUN apt-get update && \
  DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
  ca-certificates curl gnupg lsb-release && \
  mkdir -p /etc/apt/keyrings && \
  curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg && \
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null && \
  apt-get update && \
  DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends docker-ce-cli \
    libgbm1 libnss3 libasound2 libxss1 libxtst6 libatk1.0-0 libatk-bridge2.0-0 \
    libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 \
    libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 \
    libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
    libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 \
    libxshmfence1 libwayland-client0 libwayland-cursor0 libwayland-egl1 && \
  apt-get clean && \
  rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*

# Clone Moltbot repository
RUN git clone https://github.com/moltbot/moltbot.git /app

COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY patches ./patches
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN CLAWDBOT_A2UI_SKIP_MISSING=1 pnpm build
ENV CLAWDBOT_PREFER_PNPM=1
RUN pnpm ui:install
RUN pnpm ui:build
RUN pnpm dlx playwright install chromium

ENV NODE_ENV=production

USER node

CMD ["node", "dist/index.js"]
Enter fullscreen mode Exit fullscreen mode
  1. Start Moltbot: 
docker compose up -d
Enter fullscreen mode Exit fullscreen mode
  1. Pair with WhatsApp: 
docker compose exec moltbot-gateway node dist/index.js channels login
Enter fullscreen mode Exit fullscreen mode

Scan the QR code with WhatsApp on your phone (Settings → Linked Devices → Link a Device).

Configuration

Basic Configuration (config/moltbot.json) 

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3-flash-preview"
      }
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890"],
      "groupPolicy": "allowlist"
    }
  },
  "gateway": {
    "bind": "lan"
  },
  "tools": {
    "profile": "safe"
  }
}
Enter fullscreen mode Exit fullscreen mode

Tool Profiles

  • safe: Read-only tools (recommended for beginners)
  • standard: Read + basic write operations
  • full: Full shell access, Docker control, file editing

Browser Configuration

To enable web browsing without API keys:

{
  "browser": {
    "defaultProfile": "clawd",
    "executablePath": "/root/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome",
    "headless": true,
    "noSandbox": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Common Issues & Solutions

Issue 1: WhatsApp Connection Fails

Symptom: QR code doesn't appear or connection drops

Solution:

# Clear WhatsApp session and re-pair
docker compose exec moltbot-gateway rm -rf /home/node/.moltbot/channels/whatsapp
docker compose restart moltbot-gateway
docker compose exec moltbot-gateway node dist/index.js channels login
Enter fullscreen mode Exit fullscreen mode

Issue 2: Browser Relay Not Connected

Symptom: "Chrome extension relay is running, but no tab is connected"

Solution: This happens when using the default chrome profile (extension-based). Switch to the clawd profile (Playwright):

{
  "browser": {
    "defaultProfile": "clawd",
    "executablePath": "/root/.cache/ms-playwright/chromium-1208/chrome-linux64/chrome",
    "headless": true,
    "noSandbox": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Issue 3: Permission Denied on Docker Socket

Symptom: "Cannot connect to Docker daemon"

Solution: Mount the Docker socket and run as root:

services:
  moltbot-gateway:
    user: root
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
Enter fullscreen mode Exit fullscreen mode

Issue 4: Chromium Fails to Start

Symptom: "Failed to start Chrome CDP on port 18800"

Solution: Enable noSandbox mode (required when running as root):

{
  "browser": {
    "noSandbox": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Issue 5: Port 18789 Already in Use

Symptom: "Address already in use"

Solution: Change the gateway port in .env:

CLAWDBOT_GATEWAY_PORT=18790
Enter fullscreen mode Exit fullscreen mode

Issue 6: Sandbox Image Missing

Symptom: "Sandbox base image missing: moltbot-sandbox:bookworm-slim"

Solution: Build the sandbox image when prompted by moltbot doctor, or disable sandboxing:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Plugins & Skills

Built-in Plugins

WhatsApp (@moltbot/whatsapp)

Connect to WhatsApp Web for personal and group messaging.

docker compose exec moltbot-gateway node dist/index.js channels login
Enter fullscreen mode Exit fullscreen mode

Memory (@moltbot/memory)

Persistent conversation memory across sessions.

Example: "Remember that my server IP is 192.168.1.100"

Copilot Proxy (@moltbot/copilot-proxy)

Use GitHub Copilot models for free (requires Copilot subscription).

{
  "plugins": {
    "entries": {
      "copilot-proxy": {
        "enabled": true
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Skills

Skills are lightweight scripts that extend Moltbot's capabilities.

Local Places (local-places)

Search for nearby restaurants, cafes, etc. via Google Places API.

Requirements:

  • uv (Python package manager)
  • GOOGLE_PLACES_API_KEY environment variable

Example: "Find pizza places near me"

Summarize (summarize)

Extract and summarize content from URLs, podcasts, and videos.

Requirements:

  • summarize CLI tool

Example: "Summarize this YouTube video: https://youtube.com/watch?v=..."

Model Usage (model-usage)

Track AI model usage and costs (macOS only, requires CodexBar).

Example: "Show me my model usage for today"

Installing Skills

Skills are auto-discovered from the bundled skills directory. Check available skills:

docker compose exec moltbot-gateway node dist/index.js skills list
Enter fullscreen mode Exit fullscreen mode

Install missing dependencies as needed (e.g., uv for local-places).

Security Best Practices

✅ DO

  • Use DM pairing for unknown senders (dmPolicy: "pairing")
  • Run group sessions in Docker sandboxes (sandbox.mode: "non-main")
  • Set up Tailscale for remote access instead of exposing ports
  • Regularly review moltbot doctor output
  • Keep allowlists updated (allowFrom in channel config)
  • Use exec.ask: "on-miss" to approve new shell commands

⚠️ DON'T

  • Expose port 18789 to the public internet (use bind: "lan")
  • Grant shell access without understanding the risks
  • Install unverified skills from unknown sources
  • Use dmPolicy: "open" without allowlists

Advanced Use Cases

1. Server Management via WhatsApp 

You: "Check the status of my Traefik container"
Moltbot: "Traefik is running (up 3 days)"

You: "Show me the last 20 lines of Gitea logs"
Moltbot: [displays logs]

You: "Restart the job_map container"
Moltbot: "Container restarted successfully"
Enter fullscreen mode Exit fullscreen mode

2. Website Deployment 

You: "Create a new Nginx container in ~/docker/test-site with Traefik labels for test.example.com"
Moltbot: [creates docker-compose.yml, configures Traefik, deploys]
Enter fullscreen mode Exit fullscreen mode

3. Web Research 

You: "Browse to the Traefik documentation and tell me how to add basic auth middleware"
Moltbot: [opens browser, reads docs, provides answer]
Enter fullscreen mode Exit fullscreen mode

4. File Management 

You: "What's the largest folder in ~/docker?"
Moltbot: "The largest folder is ~/docker/nextcloud (45GB)"
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Check Gateway Status 

docker compose exec moltbot-gateway node dist/index.js health
Enter fullscreen mode Exit fullscreen mode

View Logs 

docker compose logs -f moltbot-gateway
Enter fullscreen mode Exit fullscreen mode

Run Diagnostics 

docker compose exec moltbot-gateway node dist/index.js doctor
Enter fullscreen mode Exit fullscreen mode

Reset Configuration 

docker compose exec moltbot-gateway node dist/index.js reset
Enter fullscreen mode Exit fullscreen mode

Conclusion: Build Your Own Private AI Assistant Today

Moltbot is the perfect solution for anyone who wants the power of ChatGPT, Claude, or Gemini without sacrificing privacy or paying monthly subscription fees. With Docker Compose, you can have your own self-hosted AI assistant running in minutes.

Whether you're a homelab enthusiast, a privacy-conscious developer, or someone who wants to automate their server management via WhatsApp, Moltbot gives you the tools to build a truly personal AI assistant.

Ready to get started? Follow the installation guide above, and you'll have your own AI assistant running on your infrastructure in less than 30 minutes.

Additional Resources

About the Author: This guide is based on my personal experience deploying Moltbot on my homelab server. I've documented all the issues I encountered and their solutions to help you avoid the same pitfalls. If you found this guide helpful, consider sharing it with others who might benefit from a self-hosted AI assistant.

Keywords: self-hosted AI, Docker AI assistant, WhatsApp AI bot, privacy-first AI, open-source ChatGPT alternative, Moltbot installation, AI gateway, Docker Compose AI

License

Moltbot is open-source software licensed under the MIT License.

Built with ❤️ by the Moltbot community

Top comments (0)