openclaw/docs/moltmates/setup.md

---
summary: "Moltmates Setup Guide - Step by step installation"
read_when:
  - 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

```bash
# 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)

```bash
# 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

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

Or if forking from upstream:

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

---

## Step 2: Install Dependencies

```bash
pnpm install
```

This installs all Node.js dependencies.

---

## Step 3: Build Moltmates

```bash
pnpm build
```

Creates the `dist/` directory with compiled code.

---

## Step 4: Build Sandbox Image

The Docker sandbox isolates user agents:

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

### Verify image:

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

### Customize sandbox (optional):

Edit `Dockerfile.sandbox` to add tools:

```dockerfile
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:
```bash
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
```

---

## Step 5: Create Configuration

```bash
# Create config directory
mkdir -p ~/.moltmate

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

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

### Minimal Configuration

```json
{
  "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:

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

---

## Step 6: Create Telegram Bot

1. Message [@BotFather](https://t.me/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](https://t.me/userinfobot)
2. Copy your numeric ID
3. Add to `allowFrom` array

---

## Step 7: Test Run

```bash
# 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

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

```ini
[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

```bash
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:

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

### Restart to Apply

```bash
sudo systemctl restart moltmate
```

### Verify User Workspaces

After users message the bot:

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

---

## Step 10: Customize Personas (Optional)

### Edit Persona Templates

```bash
# 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

```bash
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](/moltmates/faq#how-do-i-add-a-new-user)
- [Customize personas](/moltmates/personas)
- [Configure security](/moltmates/security)
- [Set up skills](/moltmates/skills)

---

## Troubleshooting

### Gateway won't start

```bash
# 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

```bash
# 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.