Skip to main content

Bridge Setup

The Bridge is a lightweight agent that connects your Meticulous machine to the Hub, enabling remote control via Claude.

Overview​

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Claude.ai  │────▶│ Hub API     │────▶│ Bridge Agent    │
│             │     │ (WebSocket) │     │ (Your Network)  │
└─────────────┘     └─────────────┘     └────────┬────────┘
                                                 │
                                                 ▼
                                        ┌─────────────────┐
                                        │   Meticulous    │
                                        │   Machine       │
                                        └─────────────────┘

The Bridge:

  • Runs on your local network (Raspberry Pi, home server, etc.)
  • Maintains a secure WebSocket connection to the Hub
  • Forwards commands from the Hub to your machine
  • Sends machine responses back to the Hub

Prerequisites​

  • A device on the same network as your Meticulous (Linux, macOS, or Windows)
  • Your machine's IP address or hostname
  • A Device Token from the Hub dashboard

Installation Options​

docker run -d \
  --name meticulous-bridge \
  --restart unless-stopped \
  -e METICULOUS_DEVICE_TOKEN=mt_xxx \
  -e METICULOUS_SERVER_URL=wss://api.meticuloushub.com/bridge \
  -e METICULOUS_API_URL=http://192.168.1.100:8080 \
  ghcr.io/naticha/meticulous-bridge:latest

Docker Compose​

version: '3.8'
services:
  meticulous-bridge:
    image: ghcr.io/naticha/meticulous-bridge:latest
    restart: unless-stopped
    environment:
      - METICULOUS_DEVICE_TOKEN=mt_xxx
      - METICULOUS_SERVER_URL=wss://api.meticuloushub.com/bridge
      - METICULOUS_API_URL=http://192.168.1.100:8080

Binary Download​

Download from GitHub Releases:

# Linux ARM64 (Raspberry Pi)
wget https://github.com/NatiCha/meticulous-bridge/releases/latest/download/meticulous-bridge-linux-arm64
chmod +x meticulous-bridge-linux-arm64
./meticulous-bridge-linux-arm64

# Linux x64
wget https://github.com/NatiCha/meticulous-bridge/releases/latest/download/meticulous-bridge-linux-amd64

# macOS (for testing)
wget https://github.com/NatiCha/meticulous-bridge/releases/latest/download/meticulous-bridge-darwin-arm64

Systemd Service​

For automatic startup on Linux:

sudo nano /etc/systemd/system/meticulous-bridge.service
[Unit]
Description=Meticulous Bridge
After=network.target

[Service]
Type=simple
User=pi
Environment=METICULOUS_DEVICE_TOKEN=mt_xxx
Environment=METICULOUS_SERVER_URL=wss://api.meticuloushub.com/bridge
Environment=METICULOUS_API_URL=http://192.168.1.100:8080
ExecStart=/home/pi/meticulous-bridge
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl enable meticulous-bridge
sudo systemctl start meticulous-bridge

Configuration​

VariableDescriptionExample
METICULOUS_DEVICE_TOKENToken from Hub dashboardmt_abc123...
METICULOUS_SERVER_URLHub WebSocket endpointwss://api.meticuloushub.com/bridge
METICULOUS_API_URLYour machine's local URLhttp://192.168.1.100:8080

Finding Your Machine's IP​

Your Meticulous machine typically uses mDNS. Try:

# Using the machine's hostname
ping meticulousXXXXXX.local

# Or find it on your network
nmap -sn 192.168.1.0/24 | grep -i meticulous

Security​

The Bridge uses several security measures:

  • TLS encryption for all Hub communication
  • Token authentication - each device has a unique token
  • API allowlist - only specific machine endpoints are accessible
  • No inbound connections - the Bridge only makes outbound connections

Troubleshooting​

Bridge won't connect to Hub​

# Check logs
docker logs meticulous-bridge

# Or for systemd
journalctl -u meticulous-bridge -f

Common issues:

  • Invalid device token
  • Network firewall blocking outbound WebSocket connections
  • DNS resolution issues

Bridge can't reach machine​

# Test machine connectivity
curl http://192.168.1.100:8080/api/v1/machine

Common issues:

  • Wrong IP address
  • Machine not on the same network
  • Machine's API not responding

Device shows offline in dashboard​

  • Verify the Bridge is running
  • Check the device token matches
  • Look for connection errors in Bridge logs