harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
zeroclaw/docs/network-deployment.md

4.9 KiB
Raw Blame History

Network Deployment — ZeroClaw on Raspberry Pi and Local Network

This document covers deploying ZeroClaw on a Raspberry Pi or other host on your local network, with Telegram and optional webhook channels.

1. Overview

Mode Inbound port needed? Use case
Telegram polling No ZeroClaw polls Telegram API; works from anywhere
Discord/Slack No Same — outbound only
Gateway webhook Yes POST /webhook, WhatsApp, etc. need a public URL
Gateway pairing Yes If you pair clients via the gateway

Key: Telegram, Discord, and Slack use long-polling — ZeroClaw makes outbound requests. No port forwarding or public IP required.

2. ZeroClaw on Raspberry Pi

2.1 Prerequisites

  • Raspberry Pi (3/4/5) with Raspberry Pi OS
  • USB peripherals (Arduino, Nucleo) if using serial transport
  • Optional: rppal for native GPIO (peripheral-rpi feature)

2.2 Install

# Build for RPi (or cross-compile from host)
cargo build --release --features hardware

# Or install via your preferred method

2.3 Config

Edit ~/.zeroclaw/config.toml:

[peripherals]
enabled = true

[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"

# Or Arduino over USB
[[peripherals.boards]]
board = "arduino-uno"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

[channels_config.telegram]
bot_token = "YOUR_BOT_TOKEN"
allowed_users = []

[gateway]
host = "127.0.0.1"
port = 3000
allow_public_bind = false

2.4 Run Daemon (Local Only)

zeroclaw daemon --host 127.0.0.1 --port 3000
  • Gateway binds to 127.0.0.1 — not reachable from other machines
  • Telegram channel works: ZeroClaw polls Telegram API (outbound)
  • No firewall or port forwarding needed

3. Binding to 0.0.0.0 (Local Network)

To allow other devices on your LAN to hit the gateway (e.g. for pairing or webhooks):

3.1 Option A: Explicit Opt-In

[gateway]
host = "0.0.0.0"
port = 3000
allow_public_bind = true

zeroclaw daemon --host 0.0.0.0 --port 3000

Security: allow_public_bind = true exposes the gateway to your local network. Only use on trusted LANs.

3.2 Option B: Tunnel (Recommended for Webhooks)

If you need a public URL (e.g. WhatsApp webhook, external clients):

  1. Run gateway on localhost:

    zeroclaw daemon --host 127.0.0.1 --port 3000

  2. Start a tunnel:

    [tunnel]
provider = "tailscale"   # or "ngrok", "cloudflare"

    Or use zeroclaw tunnel (see tunnel docs).

  3. ZeroClaw will refuse 0.0.0.0 unless allow_public_bind = true or a tunnel is active.

4. Telegram Polling (No Inbound Port)

Telegram uses long-polling by default:

  • ZeroClaw calls https://api.telegram.org/bot{token}/getUpdates
  • No inbound port or public IP needed
  • Works behind NAT, on RPi, in a home lab

Config:

[channels_config.telegram]
bot_token = "YOUR_BOT_TOKEN"
allowed_users = []      # deny-by-default, bind identities explicitly

Run zeroclaw daemon — Telegram channel starts automatically.

To approve one Telegram account at runtime:

zeroclaw channel bind-telegram <IDENTITY>

<IDENTITY> can be a numeric Telegram user ID or a username (without @).

4.1 Single Poller Rule (Important)

Telegram Bot API getUpdates supports only one active poller per bot token.

  • Keep one runtime instance for the same token (recommended: zeroclaw daemon service).
  • Do not run cargo run -- channel start or another bot process at the same time.

If you hit this error:

Conflict: terminated by other getUpdates request

you have a polling conflict. Stop extra instances and restart only one daemon.

5. Webhook Channels (WhatsApp, Custom)

Webhook-based channels need a public URL so Meta (WhatsApp) or your client can POST events.

5.1 Tailscale Funnel

[tunnel]
provider = "tailscale"

Tailscale Funnel exposes your gateway via a *.ts.net URL. No port forwarding.

5.2 ngrok

[tunnel]
provider = "ngrok"

Or run ngrok manually:

ngrok http 3000
# Use the HTTPS URL for your webhook

5.3 Cloudflare Tunnel

Configure Cloudflare Tunnel to forward to 127.0.0.1:3000, then set your webhook URL to the tunnel's public hostname.

6. Checklist: RPi Deployment

  • Build with --features hardware (and peripheral-rpi if using native GPIO)
  • Configure [peripherals] and [channels_config.telegram]
  • Run zeroclaw daemon --host 127.0.0.1 --port 3000 (Telegram works without 0.0.0.0)
  • For LAN access: --host 0.0.0.0 + allow_public_bind = true in config
  • For webhooks: use Tailscale, ngrok, or Cloudflare tunnel

7. References