Remote Hive Setup

Learn how to connect remote machines to your rbee colony.

The Problem

When you spawn a remote hive, workers need to know WHERE to send heartbeats.

❌ What Goes Wrong

# Remote hive spawned with localhost queen URL
ssh remote-machine "rbee-hive --queen-url http://localhost:7833"

Result:

• ❌ Worker sends heartbeat to localhost (its own machine!)
• ❌ Queen never receives heartbeat
• ❌ Queen thinks worker is offline
• ❌ Inference requests fail with “no worker available”

✅ The Solution

# Remote hive spawned with Queen's public IP
ssh remote-machine "rbee-hive --queen-url http://192.168.1.100:7833"

Result:

• ✅ Worker sends heartbeat to Queen’s IP
• ✅ Queen receives heartbeat
• ✅ Worker appears in registry
• ✅ Inference works

Queen Configuration

Step 1: Find Your Queen’s IP Address

# On the machine running Queen
ip addr show | grep "inet " | grep -v "127.0.0.1"

Your Queen’s IP is 192.168.1.100.

Step 2: Configure Queen’s Public Address

File: ~/.config/rbee/config.toml

[queen]
port = 7833
public_address = "192.168.1.100"  # ← Your Queen's IP

# OR use hostname
# public_hostname = "queen.local"

Step 3: Restart Queen

# Restart Queen to apply config
rbee queen stop
rbee queen start

Remote Hive Setup

Prerequisites

• SSH access to remote machine
• Queen’s public IP configured
• Firewall allows port 7833

Step 1: Install rbee on Remote Machine

# SSH into remote machine
ssh user@192.168.1.101

# Install rbee
curl -sSL https://install.rbee.dev | sh

Step 2: Start Hive with Queen URL

# On remote machine
rbee-hive --queen-url http://192.168.1.100:7833

Step 3: Verify Registration

# On Queen machine, check registered hives
curl http://localhost:7833/v1/jobs \
-H "Content-Type: application/json" \
-d '{"operation": "status"}'

You should see your remote hive in the output.

Troubleshooting

Multi-Machine Example

Architecture

┌─────────────────────────────────────────┐
│ Main Server (192.168.1.100)            │
│  - Queen (port 7833)                    │
│  - rbee-keeper (GUI)                    │
└─────────────────────────────────────────┘
           ↓ Heartbeats
    ┌──────┴──────┬──────────────┐
    │             │              │
┌───▼────┐  ┌────▼─────┐  ┌────▼─────┐
│Gaming  │  │ Mac M3   │  │ Server   │
│PC      │  │          │  │          │
│GPU 0,1 │  │ Metal    │  │ CPU only │
└────────┘  └──────────┘  └──────────┘
192.168.1.101  .102         .103

Configuration

Queen (192.168.1.100):

[queen]
port = 7833
public_address = "192.168.1.100"

Gaming PC (192.168.1.101):

rbee-hive --queen-url http://192.168.1.100:7833

Mac M3 (192.168.1.102):

rbee-hive --queen-url http://192.168.1.100:7833

Server (192.168.1.103):

rbee-hive --queen-url http://192.168.1.100:7833

Next Steps