When should I use Docker deployment?

When you want complete isolation from the host system, need reproducible deployments across environments, are running in Kubernetes, prefer containerized infrastructure, or need to run e2e tests in CI/CD.

What to do if container exits immediately?

Common causes include: missing environment variables, invalid config file, port already in use on host. Check container logs for details.

What to do if permission denied on volumes?

Ensure host directories have correct permissions, or run the container as root user.

What to do if WhatsApp QR code not displaying?

Use interactive mode: docker exec -it moltbot moltbot channels login whatsapp. The -it flags are required for QR code display.

Moltbot Docker Setup

Docker provides an optional way to run Moltbot in a container. This is useful for isolated environments, CI/CD, or if you prefer containerized deployments.

Note: Docker is optional. For most users, we recommend the macOS App or Linux systemd

TL;DR

# Clone the repo
git clone https://github.com/moltbot/moltbot.git
cd moltbot

# Build and run
docker-compose up -d

# Setup (first time)
docker exec -it moltbot pnpm moltbot setup

# Connect channels
docker exec -it moltbot pnpm moltbot channels login

# Health check
docker exec moltbot pnpm moltbot health

When to Use Docker

Docker is a good choice when you:

Want complete isolation from the host system
Need reproducible deployments across environments
Are running in Kubernetes or similar orchestration
Prefer containerized infrastructure
Need to run e2e tests in CI/CD

For development with hot reload, see Gateway Development

Prerequisites

Docker Engine 20.10+ (Install Docker)
Docker Compose v2+ (included with Docker Desktop)
Git

Quick Start with Docker Compose

1. Clone the Repository

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

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env with your settings:

# AI Provider
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

# Gateway
GATEWAY_PORT=18789

# Optional: Logging
LOG_LEVEL=info

3. Start the Container

docker-compose up -d

4. Run Initial Setup

docker exec -it moltbot pnpm moltbot setup

5. Connect Channels

docker exec -it moltbot pnpm moltbot channels login

6. Verify

docker exec moltbot pnpm moltbot health

Docker Compose Configuration

Here's the recommended docker-compose.yml:

version: '3.8'

services:
  moltbot:
    build: .
    container_name: moltbot
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      # Persist config and credentials
      - ~/.clawdbot:/root/.clawdbot
      # Persist workspace
      - ~/clawd:/root/clawd
      # Optional: mount for development
      # - ./src:/app/src
    environment:
      - NODE_ENV=production
      - GATEWAY_PORT=18789
    env_file:
      - .env

Volume Mounts

To persist data between container restarts:

Host Path	Container Path	Purpose
`~/.clawdbot`	`/root/.clawdbot`	Config and credentials
`~/clawd`	`/root/clawd`	Workspace (skills, prompts)

Important: Without volume mounts, you'll lose all configuration and credentials when the container is removed!

Building the Image

Using Docker Compose

docker-compose build

Manual Build

docker build -t moltbot:latest .

Multi-Platform Build

For ARM64 and AMD64:

docker buildx build --platform linux/amd64,linux/arm64 -t moltbot:latest .

Running Without Compose

docker run -d \
  --name moltbot \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.clawdbot:/root/.clawdbot \
  -v ~/clawd:/root/clawd \
  --env-file .env \
  moltbot:latest

Container Management

View Logs

# Follow logs
docker logs -f moltbot

# Last 100 lines
docker logs --tail 100 moltbot

Execute Commands

# Interactive shell
docker exec -it moltbot sh

# Run moltbot CLI
docker exec moltbot pnpm moltbot health
docker exec -it moltbot pnpm moltbot channels login

Restart

docker-compose restart
# or
docker restart moltbot

Stop and Remove

docker-compose down
# or
docker stop moltbot && docker rm moltbot

Updating

With Docker Compose

# Pull latest code
git pull

# Rebuild and restart
docker-compose up -d --build

Manual Update

# Stop container
docker stop moltbot

# Pull/build new image
docker build -t moltbot:latest .

# Remove old container
docker rm moltbot

# Start new container
docker run -d --name moltbot ... moltbot:latest

Health Checks

Add a health check to your docker-compose.yml:

services:
  moltbot:
    # ... other config
    healthcheck:
      test: ["CMD", "pnpm", "moltbot", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Resource Limits

Constrain container resources:

services:
  moltbot:
    # ... other config
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Networking

Expose Only Locally

For security, bind only to localhost:

ports:
  - "127.0.0.1:18789:18789"

Custom Network

services:
  moltbot:
    networks:
      - moltbot-net

networks:
  moltbot-net:
    driver: bridge

Common Issues

Container Exits Immediately

docker logs moltbot

Common causes:

Missing environment variables
Invalid config file
Port already in use on host

Permission Denied on Volumes

sudo chown -R $(id -u):$(id -g) ~/.clawdbot ~/clawd

Or run as non-root (advanced):

services:
  moltbot:
    user: "1000:1000"

Can't Connect to Gateway

docker port moltbot
# Should show: 18789/tcp -> 0.0.0.0:18789

WhatsApp QR Code Not Displaying

Use interactive mode. The -it flags are required for QR code display.

docker exec -it moltbot pnpm moltbot channels login whatsapp

Security Considerations

Never commit .env files with secrets
Use Docker secrets for production
Run as non-root user when possible
Limit container capabilities
Keep images updated

Moltbot Docker Setup

TL;DR

When to Use Docker

Prerequisites

Quick Start with Docker Compose

1. Clone the Repository

2. Configure Environment

3. Start the Container

4. Run Initial Setup

5. Connect Channels

6. Verify

Docker Compose Configuration

Volume Mounts

Building the Image

Using Docker Compose

Manual Build

Multi-Platform Build

Running Without Compose

Container Management

View Logs

Execute Commands

Restart

Stop and Remove

Updating

With Docker Compose

Manual Update

Health Checks

Resource Limits

Networking

Expose Only Locally

Custom Network

Common Issues

Security Considerations

Next Steps

Channel Integration

Configuration Reference

Security Best Practices

Moltbot Docker Setup

TL;DR

When to Use Docker

Prerequisites

Quick Start with Docker Compose

1. Clone the Repository

2. Configure Environment

3. Start the Container

4. Run Initial Setup

5. Connect Channels

6. Verify

Docker Compose Configuration

Volume Mounts

Building the Image

Using Docker Compose

Manual Build

Multi-Platform Build

Running Without Compose

Container Management

View Logs

Execute Commands

Restart

Stop and Remove

Updating

With Docker Compose

Manual Update

Health Checks

Resource Limits

Networking

Expose Only Locally

Custom Network

Common Issues

Security Considerations

Next Steps

Channel Integration

Configuration Reference

Security Best Practices

Related