Skip to Content
👋 Welcome to HowToUseMoltbot Quick Start
Getting StartedGetting Started

Getting Started

Goal: Take you from zero to your first working chat as fast as possible. We’ve made this dead simple.

The fastest route? Skip the channel setup entirely—just fire up the Control UI:

moltbot dashboard

This opens a browser-based chat on http://127.0.0.1:18789/. Done. You’re chatting.

The recommended path? Use the CLI onboarding wizard (moltbot onboard). It’s interactive and handles everything:

  • Model & auth (OAuth is easier)
  • Gateway config
  • Channels (WhatsApp, Telegram, Discord, whatever)
  • Security defaults
  • Workspace setup + skills
  • Background service (optional)

Need the deep dive? Jump to: Wizard, Setup, Pairing, Security.

Quick sandbox note: By default, group chats run in a sandbox (safer). Want your main agent on the host? Add this:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) What You Need

  • Node.js 22+ — The only hard requirement
  • pnpm — Optional, but recommended if building from source
  • Brave Search API key — Recommended for web search: 
    moltbot configure --section web
    Web tools docs

Platform notes:

macOS: Node is enough for CLI + gateway. Building the apps? Grab Xcode/CLT.

Windows: Use WSL2 (Ubuntu’s solid). Native Windows? Untested, kinda janky, skip it. WSL2 first, then Linux steps inside. Windows guide

1) Install the CLI

Mac/Linux one-liner:

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

Windows (PowerShell):

iwr -useb https://molt.bot/install.ps1 | iex

Or npm/pnpm:

npm install -g moltbot@latest
# or
pnpm add -g moltbot@latest

More options: Install docs

2) Run the Setup Wizard

This is where it all comes together:

moltbot onboard --install-daemon

The wizard walks you through:

  • Gateway mode — Local or remote?
  • Auth — OAuth (easier) or API keys. For Anthropic, API keys work best. Got Claude Code? claude setup-token reuses those creds.
  • Channels — WhatsApp QR, Telegram/Discord tokens, whatever you’re using
  • Background service — Installs as launchd (Mac) or systemd (Linux/WSL2)
  • Runtime — Use Node. Bun? Skip it (breaks WhatsApp/Telegram)
  • Gateway token — Auto-generated and saved to gateway.auth.token

Full wizard breakdown: Wizard guide

Where Your Auth Lives

Your credentials end up here:

  • Anthropic API key — Wizard stores it. Or: claude setup-token to reuse Claude Code
  • OAuth (legacy) — ~/.clawdbot/credentials/oauth.json
  • Auth profiles — ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Headless server? Do OAuth on your laptop first, then copy oauth.json to the server. Way easier than browser redirects on a headless box.

3) Start the Gateway

If you let the wizard install the service, it’s probably running already. Check:

moltbot gateway status

Running it manually?

moltbot gateway --port 18789 --verbose

Dashboard: http://127.0.0.1:18789/

Got a token? Paste it in Control UI settings (saves as connect.params.auth.token).

⚠️ Bun + WhatsApp/Telegram = broken. Use Node.

3.5) Quick Health Check

moltbot status
moltbot health
moltbot security audit --deep

Green lights? You’re good. Warnings? The output will tell you what’s up.

4) Connect Your First Channel

WhatsApp (Dead Simple)

moltbot channels login

Open WhatsApp on your phone → Settings → Linked Devices → scan. Done.

WhatsApp full guide

Telegram / Discord / Others

Wizard can handle the config. Prefer manual?

Telegram heads up: First DM sends a pairing code. Approve it (next step) or your messages get ignored.

5) Approve New People

Security first. Strangers can’t just blast your bot. They get a pairing code, you decide:

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

Nope, not you:

moltbot pairing deny whatsapp <code>

Pairing deep dive

6) Building from Source?

For the rebels:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build
pnpm build
moltbot onboard --install-daemon

7) Test the Whole Thing

Send a test message:

moltbot message send --target +15555550123 --message "yo"

Or just DM your bot on whatever channel you set up. It should hit you back.

What’s Next?

You’re up and running. Most people do this next:

Questions? Hit up Discord  or file an issue .

Setup Guide