Beanstalk Gateway

Connect your local Clawdbot to beans.talk for remote monitoring and control.

Installation

npm install -g beanstalk-gateway

Or via ClawdHub:

clawdhub install beanstalk-gateway

Quick Start

1. Get credentials from beans.talk

   • Sign up at https://beans.talk
   • Click "Add Gateway"
   • Copy your setup command

2. Configure and run

   beanstalk-gateway configure \
     --url wss://beanstalk.fly.dev/ws/gw_YOUR_ID \
     --token gt_YOUR_TOKEN
      
   beanstalk-gateway start

3. Check beans.talk - your Clawdbot should now show as "Connected"

Usage

CLI

# Start the gateway (reads from config file)
beanstalk-gateway start

# Start with explicit options
beanstalk-gateway start --url wss://... --token gt_...

# Save configuration
beanstalk-gateway configure --url wss://... --token gt_...

# Check local Clawdbot status
beanstalk-gateway status

Environment Variables

export GATEWAY_URL="wss://beanstalk.fly.dev/ws/gw_xxx"
export GATEWAY_TOKEN="gt_xxx"
export CLAWDBOT_URL="http://localhost:18789"

beanstalk-gateway start

Config File

Create ~/.clawdbot/.beanstalk/gateway.json:

{
  "url": "wss://beanstalk.fly.dev/ws/gw_xxx",
  "token": "gt_xxx",
  "clawdbotUrl": "http://localhost:18789"
}

Library Usage

import { BeanstalkGateway } from 'beanstalk-gateway';

const gateway = new BeanstalkGateway({
  url: 'wss://beanstalk.fly.dev/ws/gw_xxx',
  token: 'gt_xxx',
});

gateway.on('authenticated', () => {
  console.log('Connected to beans.talk!');
});

gateway.on('command', (commandId, action, payload) => {
  console.log('Received command:', action);
});

gateway.connect();

How It Works

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Your Machine  │      │  Beanstalk      │      │   beans.talk    │
│                 │      │  Relay (Fly.io) │      │   UI (Vercel)   │
│  ┌───────────┐  │      │                 │      │                 │
│  │ Clawdbot  │◀─┼──────┼─────────────────┼──────┼─ Commands       │
│  │  Daemon   │  │      │                 │      │                 │
│  └─────┬─────┘  │      │                 │      │                 │
│        │        │      │                 │      │                 │
│  ┌─────▼─────┐  │      │                 │      │                 │
│  │ Gateway   │──┼─────▶│  WebSocket Hub  │─────▶│  Status         │
│  │  Client   │  │      │                 │      │                 │
│  └───────────┘  │      │                 │      │                 │
└─────────────────┘      └─────────────────┘      └─────────────────┘

The gateway client:

1. Connects outbound to the relay (no port forwarding needed)
2. Reports your Clawdbot's status every 10 seconds
3. Receives and executes commands from beans.talk
4. Automatically reconnects if connection drops

Running as a Service

macOS (launchd)

# Create plist
cat > ~/Library/LaunchAgents/com.beanstalk.gateway.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.beanstalk.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which beanstalk-gateway)</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.beanstalk.gateway.plist

Linux (systemd)

sudo cat > /etc/systemd/system/beanstalk-gateway.service << EOF
[Unit]
Description=Beanstalk Gateway Client
After=network.target

[Service]
Type=simple
ExecStart=$(which beanstalk-gateway) start
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable beanstalk-gateway
sudo systemctl start beanstalk-gateway

License

MIT