BeamMolt Plugin

Remote 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.

📋 Prerequisites

Before installing BeamMolt, make sure you have:

1. Moltbot installed and running on your machine
2. A BeamShell account - Sign up at beamshell.com

🚀 Installation

Option A: Native Plugin (Recommended)

Install BeamMolt as a native Moltbot channel plugin:

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:

{
  "channels": {
    "beammolt": {
      "enabled": true,
      "relayUrl": "wss://wss.beamshell.com"
    }
  }
}

Option B: Standalone CLI

If you prefer to run BeamMolt as a separate process:

Step 1: Install Globally

npm install -g @beamshell/beammolt

Don't have npm? Install Node.js from nodejs.org - it includes npm automatically.

Step 2: Set Up BeamMolt

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

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.

🖥️ Connecting via MCP Server

To use BeamMolt from any MCP-compatible client, add the BeamShell MCP server.

MCP Server URL

https://www.beamshell.com/api/mcp

Authentication

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 <token> header.

Example: Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "beamshell": {
      "url": "https://www.beamshell.com/api/mcp"
    }
  }
}

Then restart Claude Desktop. You'll be prompted to authenticate on first use.

Example: Other MCP Clients

For clients that support remote MCP servers, configure:

• Server URL: https://www.beamshell.com/api/mcp
• Authentication: OAuth (if supported) or Bearer token

✅ Verify It's Working

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!

🔧 CLI Commands Reference

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 |

Command Options

beammolt setup

• -t, --token <token> — Use an existing BeamShell token instead of generating new one

beammolt start

• -g, --gateway <url> — Moltbot Gateway URL (default: ws://127.0.0.1:18789)
• -r, --relay <url> — BeamShell relay URL (default: wss://wss.beamshell.com)

🔄 How It Works

Native Plugin Mode (Recommended)

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────────────┐
│  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.

Standalone Mode

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  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.

❓ Troubleshooting

Native Plugin Mode

BeamMolt not starting with Moltbot

• Check Moltbot logs for errors
• Verify plugin is installed: moltbot plugins list
• Check config in ~/.moltbot/moltbot.json

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 ~/.moltbot/state/beammolt/beammolt-token.json

Standalone Mode

"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.

Both Modes

"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

📁 Configuration

Native Plugin Mode

Token is auto-generated and stored in:

• ~/.moltbot/state/beammolt/beammolt-token.json

Optional config in ~/.moltbot/moltbot.json:

{
  "channels": {
    "beammolt": {
      "enabled": true,
      "relayUrl": "wss://wss.beamshell.com"
    }
  }
}

Standalone Mode

Configuration is stored in ~/.beammolt.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.

📚 More Information

• BeamShell Website: beamshell.com
• Report Issues: GitHub Issues

License

MIT