BeamMolt plugin for Moltbot - Remote access via BeamShell relay
npm install @beamshell/beammoltRemote Moltbot access via BeamShell relay. Connect to your Moltbot from anywhere using the BeamShell MCP server.
Tested with: Claude.ai (web), Claude Desktop, Claude Code, Augment Code, and ChatGPT.
---
Before installing BeamMolt, make sure you have:
1. Moltbot installed and running on your machine
2. A BeamShell account - Sign up at beamshell.com
---
Install BeamMolt as a native Moltbot channel plugin:
``bash`
moltbot plugins install @beamshell/beammolt
That's it! On first start, BeamMolt will auto-generate a token and log an authorization URL.
#### Finding the Auth URL
The auth URL appears in your Moltbot logs on first startup. You can find it by:
1. Ask your Moltbot: Just ask "Check your logs for the BeamShell auth URL" - your Moltbot can find and return it to you
2. Check the logs manually: Look for a line like:
`
🔗 Authorize this instance: https://www.beamshell.com/auth/abc123...
#### Authorizing
1. Click the auth URL (or copy it to your browser)
2. Sign in to BeamShell if prompted
3. Authorize the connection
Once authorized, your Moltbot instance will appear as online on your BeamShell dashboard.
No separate process to run - BeamMolt starts automatically with Moltbot.
#### Configuration (Optional)
Add to your ~/.moltbot/moltbot.json to customize:
`json`
{
"channels": {
"beammolt": {
"enabled": true,
"relayUrl": "wss://wss.beamshell.com"
}
}
}
---
If you prefer to run BeamMolt as a separate process:
#### Step 1: Install Globally
`bash`
npm install -g @beamshell/beammolt
> Don't have npm? Install Node.js from nodejs.org - it includes npm automatically.
#### Step 2: Set Up BeamMolt
`bash`
beammolt setup
This will:
1. Generate a unique token for your machine
2. Display an authorization URL
3. Open your browser to authenticate
Click the link to sign in to BeamShell and authorize this machine.
#### Step 3: Start the Plugin
`bash`
beammolt start
You should see:
`
✓ Connected to BeamShell relay
✓ Connected to Moltbot Gateway
✓ Ready for remote access
Leave this running - BeamMolt needs to stay connected to receive remote commands.
> Tip: To run BeamMolt in the background, use a process manager or run it in a separate terminal window.
---
To use BeamMolt from any MCP-compatible client, add the BeamShell MCP server.
`
https://www.beamshell.com/api/mcp
The BeamShell MCP server supports two authentication methods:
| Method | Description | Use Case |
|--------|-------------|----------|
| OAuth | Interactive browser-based authentication | Claude.ai, Claude Desktop, ChatGPT |
| Bearer Token | API token in Authorization header | Programmatic access, CI/CD |
Most MCP clients (like Claude Desktop) will automatically prompt for OAuth authentication the first time you connect.
For Bearer token authentication, get your API token from beamshell.com/api-keys and pass it in the Authorization: Bearer header.
Add to your claude_desktop_config.json:
`json`
{
"mcpServers": {
"beamshell": {
"url": "https://www.beamshell.com/api/mcp"
}
}
}
Then restart Claude Desktop. You'll be prompted to authenticate on first use.
For clients that support remote MCP servers, configure:
- Server URL: https://www.beamshell.com/api/mcp
- Authentication: OAuth (if supported) or Bearer token
---
Once everything is set up:
1. Native plugin: Just start Moltbot - BeamMolt runs automatically
2. Standalone: Make sure beammolt start is running
3. In Claude Desktop, ask Claude to use BeamShell/BeamMolt tools
4. Try: "List my connected BeamMolt instances"
Claude should be able to see and communicate with your Moltbot!
---
These commands are for standalone mode only (Option B):
| Command | Description |
|---------|-------------|
| beammolt setup | Initialize BeamMolt and authorize with BeamShell |beammolt start
| | Start the plugin (connect to relay) |beammolt status
| | Show current configuration and connection status |beammolt token
| | Show or set the BeamShell token |
beammolt setup
- -t, --token — Use an existing BeamShell token instead of generating new one
beammolt start
- -g, --gateway — Moltbot Gateway URL (default: ws://127.0.0.1:18789)-r, --relay
- — BeamShell relay URL (default: wss://wss.beamshell.com)
---
`
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐
│ Claude Desktop │ │ BeamShell │ │ Your Machine │
│ (MCP Client) │────▶│ Relay │◀────│ ┌─────────────────────┐│
│ │ │ (wss://...) │ │ │ Moltbot Gateway ││
└─────────────────┘ └─────────────────┘ │ │ ┌─────────────────┐││
│ │ │ BeamMolt Channel│││
│ │ │ (native plugin) │││
│ │ └─────────────────┘││
│ └─────────────────────┘│
└─────────────────────────┘
BeamMolt runs inside the Moltbot process - no separate connection needed.
`
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Desktop │ │ BeamShell │ │ Your Machine │
│ (MCP Client) │────▶│ Relay │◀────│ ┌───────────┐ │
│ │ │ (wss://...) │ │ │ BeamMolt │ │
└─────────────────┘ └─────────────────┘ │ │ (CLI) │ │
│ └─────┬─────┘ │
│ │ WS │
│ ▼ │
│ ┌───────────┐ │
│ │ Moltbot │ │
│ │ Gateway │ │
│ └───────────┘ │
└─────────────────┘
BeamMolt runs as a separate process and connects to Moltbot via WebSocket.
1. BeamMolt makes an outbound WebSocket connection to BeamShell relay
2. Claude Desktop connects to BeamShell's MCP server
3. Commands from Claude are routed through the relay to your BeamMolt plugin
4. BeamMolt forwards them to your local Moltbot
5. Responses flow back through the same path
🔒 Security: No inbound ports required - BeamMolt only makes outbound connections.
---
BeamMolt not starting with Moltbot
- Check Moltbot logs for errors
- Verify plugin is installed: moltbot plugins list
- Check config in
Can't find the auth URL
- Ask your Moltbot: "Check your logs for the BeamShell auth URL"
- Check Moltbot logs manually on first startup
- Look for a line containing beamshell.com/auth/
- Token state is stored in
"No token configured"
Run beammolt setup first, then beammolt start.
"Cannot connect to Moltbot Gateway"
Make sure Moltbot is running. The gateway should be at ws://127.0.0.1:18789.
"Authentication required" in Claude Desktop
Make sure you're signed in to BeamShell. Visit beamshell.com and log in.
BeamMolt disconnects
The plugin automatically reconnects with exponential backoff (1s → 2s → 4s → ... up to 32s). Check your internet connection if it keeps disconnecting.
Claude can't see my Moltbot instance
1. Native: Check Moltbot is running with BeamMolt enabled
2. Standalone: Make sure beammolt start is running
3. Restart Claude Desktop
---
Token is auto-generated and stored in:
- ~/.moltbot/state/beammolt/beammolt-token.json
Optional config in ~/.moltbot/moltbot.json:`json`
{
"channels": {
"beammolt": {
"enabled": true,
"relayUrl": "wss://wss.beamshell.com"
}
}
}
Configuration is stored in ~/.beammolt.json:
`json`
{
"token": "your-beamshell-token",
"relayUrl": "wss://wss.beamshell.com",
"gatewayUrl": "ws://127.0.0.1:18789",
"reconnect": true
}
You shouldn't need to edit this file manually - use the beammolt` commands instead.
---
- BeamShell Website: beamshell.com
- Report Issues: GitHub Issues
---
MIT