openclaw/docs/moltmates/setup.md

summary	read_when
Moltmates Setup Guide - Step by step installation	Installing Moltmates for the first time Setting up multi-user deployment

🛠️ Moltmates Setup Guide

Complete step-by-step installation for Moltmates multi-user deployment.

---

Prerequisites

System Requirements

Component	Minimum	Recommended
CPU	2 cores	4+ cores
RAM	4 GB	8+ GB
Disk	20 GB	50+ GB SSD
OS	Linux (Debian/Ubuntu)	Ubuntu 22.04+

Software Requirements

# Node.js ≥22
node --version  # Should be 22.x+

# Docker
docker --version  # Should be 20.x+

# pnpm (recommended)
pnpm --version  # Or npm/bun

Install Prerequisites (Ubuntu/Debian)

# Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in

# pnpm
npm install -g pnpm

---

Step 1: Clone Repository

cd ~
git clone https://github.com/YOUR_FORK/moltmates
cd moltmates

Or if forking from upstream:

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

---

Step 2: Install Dependencies

pnpm install

This installs all Node.js dependencies.

---

Step 3: Build Moltmates

pnpm build

Creates the dist/ directory with compiled code.

---

Step 4: Build Sandbox Image

The Docker sandbox isolates user agents:

docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .

Verify image:

docker images | grep moltmate-sandbox
# Should show: moltmate-sandbox   bookworm-slim   ...

Customize sandbox (optional):

Edit Dockerfile.sandbox to add tools:

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    poppler-utils \
    imagemagick \
    ffmpeg \
    # Add more packages here
    && rm -rf /var/lib/apt/lists/*

Rebuild after changes:

docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .

---

Step 5: Create Configuration

# Create config directory
mkdir -p ~/.moltmate

# Copy example config
cp moltmate.example.json ~/.moltmate/moltmate.json

# Edit config
nano ~/.moltmate/moltmate.json

Minimal Configuration

{
  "gateway": {
    "port": 18790,
    "bind": "127.0.0.1"
  },
  "agents": {
    "main": {
      "model": "anthropic/claude-sonnet-4-5",
      "provider": "anthropic"
    }
  },
  "providers": {
    "anthropic": {
      "apiKey": "${ANTHROPIC_API_KEY}"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "allowlist",
      "allowFrom": ["YOUR_TELEGRAM_ID"]
    }
  },
  "sandbox": {
    "mode": "all",
    "scope": "session",
    "workspaceAccess": "rw"
  },
  "tools": {
    "allow": ["read", "write", "edit", "exec", "web_search", "web_fetch"],
    "exec": {
      "security": "allowlist",
      "safeBins": ["cat", "head", "tail", "grep", "wc", "ls"]
    }
  }
}

Environment Variables

Create .env file or export:

export ANTHROPIC_API_KEY="sk-ant-..."
export TELEGRAM_BOT_TOKEN="123456:ABC..."

---

Step 6: Create Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot
3. Choose name and username
4. Copy the token (looks like 123456789:ABCdefGHI...)
5. Add to config as TELEGRAM_BOT_TOKEN

Get Your Telegram ID

1. Message @userinfobot
2. Copy your numeric ID
3. Add to allowFrom array

---

Step 7: Test Run

# Development mode (foreground)
pnpm dev

You should see:

Gateway starting on 127.0.0.1:18790
Telegram connected
Ready for messages

Test by messaging your bot on Telegram!

---

Step 8: Production Setup (systemd)

Create Service File

sudo nano /etc/systemd/system/moltmate.service

[Unit]
Description=Moltmates Gateway
After=network.target docker.service
Requires=docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/root/moltmates
Environment=NODE_ENV=production
Environment=ANTHROPIC_API_KEY=sk-ant-...
Environment=TELEGRAM_BOT_TOKEN=123456:ABC...
ExecStart=/usr/bin/node dist/cli.js gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable & Start

sudo systemctl daemon-reload
sudo systemctl enable moltmate
sudo systemctl start moltmate

# Check status
sudo systemctl status moltmate

# View logs
sudo journalctl -u moltmate -f

---

Step 9: Add Users

Add to Allowlist

Edit config to add user IDs:

"channels": {
  "telegram": {
    "allowFrom": [
      "YOUR_ID",
      "FRIEND_ID",
      "FAMILY_ID"
    ]
  }
}

Restart to Apply

sudo systemctl restart moltmate

Verify User Workspaces

After users message the bot:

ls ~/.moltmate/users/
# Should show: telegram_123456  telegram_789012  etc.

---

Step 10: Customize Personas (Optional)

Edit Persona Templates

# Cami persona
nano /root/moltmates/templates/souls/cami.md

# Molty persona  
nano /root/moltmates/templates/souls/molty.md

# Custom template
nano /root/moltmates/templates/souls/custom.md

Rebuild After Changes

cd /root/moltmates
pnpm build
sudo systemctl restart moltmate

---

Verification Checklist

• Node.js ≥22 installed
• Docker running
• Sandbox image built
• Config file created
• API keys set
• Telegram bot created
• Your ID in allowFrom
• Gateway starts without errors
• Bot responds to messages
• User workspace created in ~/.moltmate/users/

---

Next Steps

• Add more users
• Customize personas
• Configure security
• Set up skills

---

Troubleshooting

Gateway won't start

# Check logs
journalctl -u moltmate -n 50

# Common issues:
# - Port already in use: change gateway.port
# - Invalid config: validate JSON
# - Missing env vars: check ANTHROPIC_API_KEY, etc.

Docker sandbox fails

# Check Docker is running
docker ps

# Rebuild image
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .

# Check for orphan containers
docker ps -a | grep moltmate

Bot doesn't respond

1. Verify bot token is correct
2. Check user ID is in allowFrom
3. Verify gateway is running
4. Check logs for errors

---

Setup complete! 🎉

Your Moltmates server is now ready to serve multiple users with isolated AI assistants.