MoltBot is a personal AI assistant that runs on your own devices. It integrates with multiple messaging platforms (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat) and provides AI-powered assistance across all your channels.

Features

Multi-channel Support: WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, BlueBubbles, Microsoft Teams, Matrix, Zalo, WebChat
Local-first Gateway: Single control plane for sessions, channels, tools, and events
Multi-agent Routing: Route inbound channels to isolated agents with per-agent sessions
Voice Wake + Talk Mode: Always-on speech for macOS/iOS/Android with ElevenLabs
Live Canvas: Agent-driven visual workspace with A2UI
First-class Tools: Browser, canvas, nodes, cron, sessions, and channel-specific actions
Companion Apps: macOS menu bar app + iOS/Android nodes
Skills Platform: Bundled, managed, and workspace skills with install gating

Quick Start

Copy the example environment file:
```
cp .env.example .env
```

Generate a secure gateway token:

# Using OpenSSL
openssl rand -hex 32

# Or using Python
python3 -c "import secrets; print(secrets.token_hex(32))"

Edit .env and set at least:
- MOLTBOT_GATEWAY_TOKEN - Your generated token
- ANTHROPIC_API_KEY or OPENAI_API_KEY - If using API key auth
Start the gateway:
```
docker compose up -d
```
Access the Control UI:
- Open http://localhost:18789 in your browser
- Enter your gateway token when prompted

Configuration

Gateway Access

The gateway can be accessed in two ways:

Loopback (MOLTBOT_GATEWAY_BIND=loopback): Only accessible from the host machine (127.0.0.1)
LAN (MOLTBOT_GATEWAY_BIND=lan): Accessible from your local network (0.0.0.0)

For production deployments, consider:

Using Tailscale Serve/Funnel for secure remote access
Setting up SSH tunnels
Implementing reverse proxy with authentication

Model Configuration

MoltBot supports multiple AI model providers:

Anthropic Claude (Recommended): Claude Pro/Max with OAuth or API key
OpenAI: ChatGPT/Codex with OAuth or API key
Custom Providers: Configure via the Control UI or config file

Set API keys in .env or use OAuth authentication through the onboarding wizard.

Channel Integration

To connect messaging platforms:

WhatsApp: Use the CLI to link device

docker compose run --rm moltbot-cli channels login

Telegram: Set TELEGRAM_BOT_TOKEN in config
Discord: Set DISCORD_BOT_TOKEN in config
Slack: Set SLACK_BOT_TOKEN and SLACK_APP_TOKEN in config

See the official documentation for detailed setup instructions.

Using the CLI

The CLI service is available via the cli profile:

# Run onboarding wizard
docker compose run --rm --service-ports moltbot-cli onboard

# List providers
docker compose run --rm moltbot-cli providers list

# Send a message
docker compose run --rm moltbot-cli message send --to +1234567890 --message "Hello"

# Check health
docker compose run --rm moltbot-cli health --port 18789

Security Considerations

Gateway Token: Keep your gateway token secure. This is the authentication method for the Control UI and WebSocket connections.
DM Access: By default, MoltBot uses pairing mode for direct messages from unknown senders. They receive a pairing code that you must approve.
Network Exposure: If exposing the gateway beyond localhost, use proper authentication and encryption:
- Set up Tailscale for secure remote access
- Use SSH tunnels
- Implement reverse proxy with HTTPS and authentication
API Keys: Never commit API keys to version control. Use .env file or secrets management.
Sandbox Mode: For group/channel safety, enable sandbox mode to run non-main sessions in Docker containers.

Advanced Configuration

Resource Limits

Adjust CPU and memory limits in .env:

MOLTBOT_CPU_LIMIT=2.0
MOLTBOT_MEMORY_LIMIT=2G
MOLTBOT_CPU_RESERVATION=1.0
MOLTBOT_MEMORY_RESERVATION=1G

Persistent Data

Data is stored in two Docker volumes:

moltbot_config: Configuration files and credentials (~/.clawdbot)
moltbot_workspace: Agent workspace and skills (~/clawd)

To backup your data:

docker run --rm -v moltbot_config:/data -v $(pwd):/backup alpine tar czf /backup/moltbot-config-backup.tar.gz /data
docker run --rm -v moltbot_workspace:/data -v $(pwd):/backup alpine tar czf /backup/moltbot-workspace-backup.tar.gz /data

Custom Configuration File

Create a custom config file at ~/.clawdbot/moltbot.json (inside the container):

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-5",
        "fallbacks": ["anthropic/claude-sonnet-4-5", "openai/gpt-4o"]
      }
    }
  }
}

Troubleshooting

Gateway Won't Start

Check logs: docker compose logs moltbot-gateway
Verify gateway token is set in .env
Ensure port 18789 is not already in use

Can't Access Control UI

Verify gateway bind setting matches your access method
Check firewall rules if accessing from another machine
Ensure container is healthy: docker compose ps

Model API Errors

Verify API keys are correctly set in .env
Check API key validity and quota
Review logs for specific error messages

Run Doctor Command

The doctor command helps diagnose common issues:

docker compose run --rm moltbot-cli doctor

Documentation

License

MoltBot is released under the MIT License. See the LICENSE file for details.

README.md

MoltBot