How to Setup Moltbot on Ubuntu: A Complete Self-Hosted AI Gu

The Ultimate Guide: Setting Up a Self-Hosted AI Agent (Moltbot) on Ubuntu

Running an AI assistant locally gives you privacy, control, and zero latency. But simply installing it isn’t enough—you need to configure the brain (Models), the nervous system (Gateway), and the hands (Skills).

In this guide, we will cover the end-to-end setup of Moltbot on an Ubuntu VM, moving beyond the basics to configure the Gateway, secure your connection with Pairing, and install custom Skills.

Prerequisites

• OS: Ubuntu 20.04 LTS or newer (or WSL2 on Windows).

• Runtime: Node.js v22+ (Required).

• Access: Root/Sudo privileges.

Step 1: Core Installation

First, we get the binaries onto your machine. The official script handles the global installation and dependencies.

Bash

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 22 (using NVM is recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

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

Step 2: Gateway Configuration (The "Brain")

The Gateway is the heart of Moltbot. It routes messages between your chat apps and the AI models.

Run the onboard wizard to generate your initial config:

Bash

moltbot onboard --install-daemon

Understanding moltbot.json

Moltbot stores its config at ~/.moltbot/moltbot.json. You can manually tune the Gateway here. For a VM, you might want to ensure the gateway binds strictly to localhost for security, using an SSH tunnel to access it remotely.

Recommended VM Configuration:

JSON

{
  "gateway": {
    "bind": "loopback",  // Keeps it internal (127.0.0.1)
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "generate-a-strong-random-token-here"
    }
  }
}

Step 3: Model Setup (The Intelligence)

Moltbot doesn't "think" on its own; it uses LLMs. You need to configure which "brain" it uses.

During the onboard process, you will be asked for API keys. You can also swap models later by editing the config file.

• Anthropic (Claude 3.5 Sonnet): Highly recommended for coding and complex logic.

• OpenAI (GPT-4o): Great for general conversation and speed.

To switch models without re-running the wizard, you can use the CLI:

Bash

moltbot config set models.default "claude-3-5-sonnet"
moltbot config set apiKeys.anthropic "sk-ant-..."

Step 4: Channel Integration

This is how you talk to your bot. Moltbot supports "Unified Messaging," meaning it remembers context regardless of where you chat.

Option A: WhatsApp (The Daily Driver)

WhatsApp integration uses the Baileys protocol (similar to WhatsApp Web).

1. Run the login command:

   Bash

   text

   moltbot channels login whatsapp
   

2. Your terminal will generate a QR code.

3. Open WhatsApp on your phone $\rightarrow$ Linked Devices $\rightarrow$ Link a Device.

4. Scan the terminal screen.

   • VM Tip: If the QR code renders poorly in your SSH client, try maximizing the window or reducing the font size.

Option B: Telegram (The Developer Choice)

1. Message @BotFather on Telegram.

2. Create a new bot (/newbot) and get the API Token.

3. Add it to Moltbot:

   Bash

   text

   moltbot config set channels.telegram.botToken "YOUR_TOKEN_HERE"
   moltbot config set channels.telegram.enabled true
   # Restart to apply
   moltbot restart
   

Step 5: The Pairing System (Security)

Since your Moltbot runs on a server, you don't want strangers messaging your bot and using up your API credits. Moltbot uses a Pairing System by default.

1. The Trigger: When you (or anyone) first messages the bot on WhatsApp/Telegram, the bot will reply:

   "Access Denied. Pairing Code: ABC-123"

2. The Approval: Go to your Ubuntu terminal and run:

   Bash

   text

   # List pending requests
   moltbot pairing list
   
   # Approve your specific device
   moltbot pairing approve whatsapp ABC-123
   

3. The Result: That specific user ID is now "Allowlisted." All other users remain blocked.

Step 6: Skills System (Making it Work)

A "Skill" is a definition file that tells the AI how to use tools.

Installing Community Skills

MoltHub is the package manager for skills.

Bash

# Install a weather checking skill
molthub install weather-forecast

# Install a web search skill (requires Brave Search API)
molthub install web-browser

Creating Custom Skills

You can teach Moltbot to manage your Ubuntu VM. Create a file at ~/moltbot-workspace/skills/vm-stats/SKILL.md:

Markdown

---
name: vm-stats
description: Check the server CPU and Memory usage
---

## Instructions
When the user asks for server health or stats:
1. Run the command: `free -h && uptime`
2. Summarize the memory usage and load average in a friendly message.

Moltbot automatically detects changes to SKILL.md files. You can now ask: "How is the server doing?" and it will execute the command and report back.

Step 7: Verification & Maintenance

Finally, ensure the daemon is healthy.

Bash

# Check connection status for all channels
moltbot status --all

# View live logs (great for debugging)
moltbot logs --follow

Your Moltbot is now fully configured! It is securely bound to your VM, accessible only by you via the Pairing system, and equipped with custom skills to handle your tasks.