Moltbot Gateway Development
This guide is for developers who want to work on the TypeScript Gateway with hot reload, or run bleeding-edge versions.
TL;DR
# Terminal 1: Start the dev Gateway
pnpm install
pnpm gateway:watch
# Terminal 2 (optional): Run macOS app from source
./scripts/restart-mac.sh
# In Moltbot.app: Set Connection Mode to "Local"
# Verify:
moltbot healthWhen to Use This Workflow
Choose the Gateway Development workflow if you:
- Want to contribute to Moltbot
- Need hot reload when editing TypeScript
- Want to run the latest unreleased code
- Are debugging Gateway issues
For normal usage, see macOS App Setup
Prerequisites
- Node.js >= 22
- pnpm
- Git
- (Optional) Moltbot.app installed
Step-by-Step Guide
1. Clone the Repository
git clone https://github.com/moltbot/moltbot.git
cd moltbot2. Install Dependencies
pnpm install3. Start the Dev Gateway
pnpm gateway:watchThis command:
- Compiles the TypeScript Gateway
- Starts the WebSocket server on ws://127.0.0.1:18789
- Watches for file changes and auto-reloads
You should see output like:
Gateway started on ws://127.0.0.1:18789
Watching for changes...4. Connect the macOS App (Optional)
If you want to use the macOS app UI with your dev Gateway:
- Open Moltbot.app
- Click the menu bar icon
- Go to Settings → Connection
- Set Connection Mode to Local
The app will now connect to your running Gateway. You should see: "Using existing gateway on port 18789..."
5. (Optional) Run macOS App from Source
For full bleeding-edge development, run the macOS app from source too:
./scripts/restart-mac.sh6. Verify Setup
moltbot healthAll checks should pass. The Gateway status should show your dev instance.
Development Commands
| Command | Description |
|---|---|
pnpm gateway:watch | Start Gateway with hot reload |
pnpm gateway:build | Build Gateway for production |
pnpm test | Run test suite |
pnpm lint | Run linter |
pnpm typecheck | TypeScript type checking |
Gateway Configuration
Port Configuration
Default port is 18789. To change it:
# Via environment variable
GATEWAY_PORT=18790 pnpm gateway:watch
# Or in ~/.clawdbot/moltbot.json
{
"gateway": {
"port": 18790
}
}Important: Keep the macOS app and CLI on the same port, or they won't be able to communicate.
Debug Mode
Enable verbose logging:
DEBUG=moltbot:* pnpm gateway:watch
# Or for specific modules:
DEBUG=moltbot:gateway,moltbot:channels pnpm gateway:watchArchitecture Overview
┌─────────────────────┐ WebSocket ┌─────────────────────┐
│ Moltbot.app │◄──────────────────►│ Gateway │
│ (Menu Bar UI) │ :18789 │ (TypeScript) │
└─────────────────────┘ └──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Channels │
│ (WhatsApp, TG...) │
└─────────────────────┘The Gateway is the core engine that:
- Manages AI model connections
- Handles channel integrations
- Processes messages and executes skills
- Stores sessions and memories
Common Issues
Port Already in Use
# Find what's using the port
lsof -i :18789
# Kill it or use a different port
GATEWAY_PORT=18790 pnpm gateway:watchApp Shows "Disconnected"
- Ensure Gateway is running (pnpm gateway:watch)
- Check app is set to "Local" mode
- Verify ports match
Hot Reload Not Working
Check for TypeScript errors in the terminal. Syntax errors will prevent reload.
Updating Your Development Environment
# Pull latest changes
git pull
# Update dependencies (if lockfile changed)
pnpm install
# Restart the Gateway
pnpm gateway:watchKeep ~/clawd and ~/.clawdbot/ for your personal stuff. Don't put custom prompts or config in the moltbot repo - they'll be lost on git pull.