USER MANUAL · SYSTEM

Infrastructure

Monitor federation peers, edge agents, and deployment health from a single pane.

/infrastructure

Overview#

The Infrastructure page consolidates system-level concerns: federation peer management, edge agent monitoring, and overall deployment health. It is the go-to place when you need to verify that your ClawButler instance is properly connected to remote peers and that all edge agents are reporting in.

Federation enables cross-instance Agent collaboration via the A2A (agent-to-agent) protocol. Each peer is registered with a remote_peer_id and an outbound_secret, and calls can flow inbound or outbound through configured routing rules.

Prerequisites#

Prerequisites

A deployed and running ClawButler instance
At least one federation peer or edge agent configured (for full functionality)

Expected Results#

After setup, the Infrastructure page shows:

-Federation peer list with connection status, last heartbeat, and call counts
-Edge agent status panel showing connected agents, uptime, and tunnel health
-Service health overview with green/amber/red indicators for each component

Web Operations#

The Infrastructure page is organized into three sections accessible via the sidebar:

Federation Peers

View all registered peers with their remote_peer_id, connection status, and last heartbeat timestamp. Add new peers by providing the remote instance URL and outbound_secret. Inbound and outbound A2A call logs are shown per peer.

Edge Agent Status

Lists all edge agents connected via WSS tunnel. Each entry shows the agent hostname, uptime, last sync timestamp, and tunnel health. Disconnected agents are highlighted in red.

Service Health

A unified health dashboard showing the status of API, database, Valkey cache, and connected gateways. Each component displays a green/amber/red indicator with response latency.

CLI Operations#

Check overall infrastructure status including services, peers, and edge agents

Terminal

$ ap infrastructure status

List federation peers with connection status

FAQ#

Q: What is federation?

A: Federation allows multiple ClawButler instances to collaborate by routing A2A (agent-to-agent) calls between them. Each instance registers the other as a peer with a shared secret, enabling cross-instance agent communication.

Q: How do I add a federation peer?

A: Navigate to Infrastructure > Federation Peers and click Add Peer. Provide the remote instance URL and an outbound_secret. The remote instance must also register your instance as a peer for bidirectional communication.

Q: What is the difference between an edge agent and a connector?

A: A connector is a configuration that tells ClawButler how to reach an OpenClaw gateway (URL, credentials). An edge agent is a lightweight process that runs alongside the gateway, maintaining a persistent WSS tunnel to ClawButler Cloud for real-time sync and cost data.