Multi-node & Observability

This page covers the optional components needed when running XGopilot across multiple nodes.

Single node?

If you run a single XGopilot instance, you can skip this page. These components are only needed for horizontal scaling.

Architecture

Ingress/Webhook → Routing Service → XGopilot Nodes
                         |
                         ├── Boss System (task coordination)
                         ├── Log System (centralized logs)
                         |
                      Database (shared)

Components

Routing Service

Provides sticky routing so webhook events for the same issue/PR reach the same XGopilot node.

Prerequisites: Shared database (PostgreSQL/MySQL) accessible by all nodes.

ROUTER_HTTP_ADDR=:8080
ROUTER_DB_DSN="postgres://user:pass@db:5432/xgopilot?sslmode=disable"
ROUTER_HEALTH_PATH=/health

Boss System

Coordinates long-running and queued tasks across nodes.

BOSS_ENDPOINT="http://router:8080"
BOSS_TOKEN="shared-boss-token"

Log System

Centralizes task logs for observability. Can feed into your existing log pipeline (Loki, ELK, etc.).

LOG_ENDPOINT="http://router:8080"
LOG_TOKEN="shared-log-token"
LOG_RETENTION_DAYS=14

Deployment Notes

Deploy the shared database before scaling out
Keep all XGopilot nodes in the same network plane as the routing service
Point your webhook ingress to the routing service, not individual nodes
Use a load balancer for the routing service endpoint

Config templates

See config.example.yaml and router-config.example.yaml in the repository for full configuration examples.

Deployment

FAQ