HomeAboutDownloadFAQ

Moltbot on Linux

Run your personal AI assistant on any Linux distribution. Perfect for servers, VPS, Raspberry Pi, and desktop. The Gateway runs 24/7 with systemd or Docker.

Why Run Moltbot on Linux?

Linux is the ideal platform for running Moltbot as an always-on personal AI assistant. Run it on a server, VPS, or Raspberry Pi for 24/7 availability.

🖥️

Always-On Server

Run on a headless server or VPS for 24/7 availability without a desktop

🐳

Docker Ready

Official Docker images for easy deployment and container orchestration

🔧

Systemd Integration

Native systemd service for automatic startup and process management

System Requirements

Moltbot runs on most modern Linux distributions with minimal resource requirements.

DistributionsUbuntu 20.04+, Debian 11+, Fedora 36+, CentOS/RHEL 8+, Arch Linux, Alpine
Architecturex86_64 (amd64), ARM64 (aarch64)
Node.jsv22.0.0 or later (LTS recommended)
RAM2 GB minimum, 4 GB recommended (8 GB+ for local models)
Storage500 MB for base install + workspace data
NetworkInternet connection for AI API calls

💡 Raspberry Pi: Moltbot runs great on Raspberry Pi 4/5 with 4GB+ RAM on 64-bit Raspberry Pi OS. Perfect for a dedicated home AI assistant.

Quick Install (Recommended)

The fastest way to get started is using npm with the interactive onboarding wizard.

Step 1: Install Node.js 22

Choose your distribution:

Ubuntu / Debian

# Using NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should be v22.x.x

Fedora / RHEL / CentOS

# Using NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

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

Arch Linux

sudo pacman -S nodejs npm

Step 2: Install Moltbot

Install Moltbot globally via npm:

npm install -g moltbot@latest

Step 3: Run the Onboarding Wizard

The wizard guides you through initial setup and installs the systemd service:

moltbot onboard --install-daemon

This will:

  • Create your workspace at ~/.moltbot/
  • Configure your AI provider (Claude, GPT, Gemini, etc.)
  • Set up the Gateway as a systemd user service
  • Guide you through channel connections

Step 4: Start Using Moltbot

Once setup is complete, you can interact via CLI or connected channels:

# Chat via command line
moltbot chat "Hello, what can you do?"

# Or open the web interface
moltbot ui

Docker Installation

Docker is the easiest way to deploy Moltbot on servers, NAS devices, or in container orchestration environments.

Quick Start with Docker

# Pull the latest image
docker pull moltbot/moltbot:latest

# Run with a persistent volume for workspace data
docker run -d \
  --name moltbot \
  -p 18789:18789 \
  -v moltbot-data:/root/.moltbot \
  -e ANTHROPIC_API_KEY="your-api-key" \
  moltbot/moltbot:latest

Docker Compose (Recommended)

Create a docker-compose.yml file:

version: '3.8'

services:
  moltbot:
    image: moltbot/moltbot:latest
    container_name: moltbot
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - moltbot-data:/root/.moltbot
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # Or use other providers:
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
      # - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY}

volumes:
  moltbot-data:

Then run:

docker-compose up -d

💡 Tip: For channel connections that require QR codes (WhatsApp), attach to the container: docker exec -it moltbot moltbot channel add whatsapp

Systemd Service Management

Moltbot runs as a systemd user service for automatic startup and process management.

# Install the daemon (if not done during onboard)
moltbot daemon install

# Start the daemon
moltbot daemon start

# Check daemon status
moltbot daemon status

# Stop the daemon
moltbot daemon stop

# View daemon logs
moltbot daemon logs

# Follow logs in real-time
moltbot daemon logs --follow

The systemd service is installed at:

~/.config/systemd/user/moltbot.service

⚠️ Headless Servers: To run the daemon without being logged in, enable lingering for your user: sudo loginctl enable-linger $USER

Configure AI Provider

Moltbot supports multiple AI providers. Set your API key as an environment variable or configure in the workspace.

🟣 Anthropic Claude (Recommended)

Best overall performance for agentic tasks.

export ANTHROPIC_API_KEY="sk-ant-..."

🟢 OpenAI GPT

GPT-4o, GPT-4 Turbo, GPT-3.5 support.

export OPENAI_API_KEY="sk-..."

🔵 Google Gemini

Gemini 1.5 Pro and Flash.

export GOOGLE_AI_API_KEY="..."

🏠 Local Models (Ollama)

Run models locally for privacy.

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

Configure your provider in the workspace:

# Interactive configuration
moltbot config set model.provider anthropic
moltbot config set model.name claude-sonnet-4-20250514

# Or edit directly
nano ~/.moltbot/config.yaml

Connect Chat Channels

Connect Moltbot to your existing chat apps. On Linux, all channels except iMessage are available.

# Connect WhatsApp (scan QR code)
moltbot channel add whatsapp

# Connect Telegram (enter bot token)
moltbot channel add telegram

# Connect Slack (OAuth flow)
moltbot channel add slack

# Connect Discord (enter bot token)
moltbot channel add discord

# Connect Signal (requires signal-cli setup)
moltbot channel add signal

# List connected channels
moltbot channel list

💡 Signal on Linux: Signal channel requires signal-cli to be installed separately. See signal-cli documentation for setup instructions.

Remote Access with Tailscale

Access your Moltbot Gateway remotely using Tailscale Serve or Funnel.

Tailscale Setup

# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Connect to your tailnet
sudo tailscale up

# Configure Moltbot to use Tailscale Serve
moltbot config set gateway.tailscale.mode serve

# Or for public access (requires password auth)
moltbot config set gateway.tailscale.mode funnel
moltbot config set gateway.auth.mode password

💡 Remote Gateway: Linux is ideal for running a remote Gateway. Your macOS/iOS/Android devices can connect as nodes to execute device-local actions while the Gateway runs on Linux 24/7.

Troubleshooting

Common issues and solutions for Linux installation.

Run Diagnostics

The moltbot doctor command checks your setup and identifies issues:

moltbot doctor

"command not found: moltbot"

npm global binaries not in PATH. Add to your shell config (~/.bashrc or ~/.zshrc):

export PATH="$PATH:$(npm config get prefix)/bin"

"EACCES: permission denied" errors

Avoid using sudo with npm. Fix npm permissions or use nvm:

# Option 1: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Option 2: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Daemon not starting on boot (headless)

Enable user lingering to run systemd user services without login:

sudo loginctl enable-linger $USER

WhatsApp QR code not displaying in SSH

Use the web UI for channel setup, or ensure your terminal supports QR rendering:

# Start the web UI
moltbot ui
# Then open http://localhost:18789 in a browser

Linux FAQ