Skip to content

Multi-host deployment (Docker host + ZeroClaw host)

The default setup in compose.all-in-one.yml runs everything on one Docker host. This document describes the multi-host split: xiaozhi-server on a Linux Docker host and ZeroClaw + the bridge on a separate ZeroClaw host.

When you'd want this

  • Dedicated hardware for the brain. ZeroClaw runs as a native binary (Rust, not containerized). If you already have a Pi running ZeroClaw for other channels (chat, CLI, other agents), keeping the bridge there avoids duplicating the install.
  • Resource isolation. The voice pipeline (ASR model loading, TTS) and the LLM bridge have different resource profiles. Splitting them across hosts avoids contention.
  • Docker host already in use. If you already run a Linux Docker host (NAS, home-server, mini-PC) and don't want to install Rust/ZeroClaw tooling on it, the Pi is a natural home for the bridge.

How it differs from all-in-one

Aspect All-in-one Multi-host
Compose file compose.all-in-one.yml docker-compose.yml (xiaozhi only)
Bridge runs as Docker container systemd service on the Pi
LLM URL in .config.yaml http://bridge:8080/api/message/stream (Docker network) http://<ZEROCLAW_HOST>:8080/api/message/stream (real LAN IP)
ZeroClaw install On the Docker host, bind-mounted into the bridge container Native on the Pi (cargo install zeroclaw)
Network Docker bridge network between services LAN — xiaozhi-server reaches the Pi over WiFi/Ethernet

Setup

The main SETUP guide and architecture page already document this layout in detail. The short version:

  1. Docker host:
  2. Clone this repo to <XIAOZHI_PATH>.
  3. Edit data/.config.yaml: set LLM.ZeroClawLLM.url to http://<ZEROCLAW_HOST>:8080/api/message/stream.

  4. Run docker compose up -d (uses the standard docker-compose.yml).

  5. ZeroClaw host:

  6. Install ZeroClaw: cargo install zeroclaw (see zeroclaw-labs/zeroclaw).
  7. Configure the agent: edit ~/.zeroclaw/config.toml with your LLM provider, API keys, and persona.
  8. Copy bridge.py and bridge/requirements.txt to <BRIDGE_PATH>.
  9. Create a venv and install deps: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt.

  10. Install the systemd unit: copy zeroclaw-bridge.service to /etc/systemd/system/, edit paths, then systemctl enable --now zeroclaw-bridge.

  11. StackChan device:

  12. Set OTA URL to http://<XIAOZHI_HOST>:8003/xiaozhi/ota/.

Migrating from all-in-one to multi-host

  1. Stop the all-in-one stack: docker compose -f compose.all-in-one.yml down.
  2. Edit data/.config.yaml: change the LLM URL from http://bridge:8080/... to http://<ZEROCLAW_HOST>:8080/....
  3. Set up the Pi as described above.
  4. Start xiaozhi-server alone: docker compose up -d (standard docker-compose.yml).

Reference