Gateway & Protocol

The single JSON-RPC/WebSocket server every surface talks to.

The gateway is the single server every PoorMad surface connects to. It speaks JSON-RPC over WebSocket.

Protocol

Surfaces open a WebSocket to wss://<host>/api/ws (or ws://127.0.0.1:8765/api/ws locally) and exchange JSON-RPC 2.0 messages: requests, notifications, and results.

Authentication

• Local loopback uses an auto-generated session ticket.
• Remote binds use a token (POORMAD_TOKEN) passed as a query param or header.
• Use --insecure only for trusted LAN / self-hosted setups.

GatewayClient

from poormad import GatewayClient
client = GatewayClient(
    base_url="wss://your-agent.local/api/ws",
    token=os.environ["POORMAD_TOKEN"],
)
await client.connect()

Configuring the bind

# config.yaml
gateway:
  bind: 0.0.0.0:8765   # listen on all interfaces
  token: "${POORMAD_TOKEN}"