concepts / federation

Federation

Kite federation connects multiple Kite instances — self-hosted and cloud, staging and production — into a unified event mesh. Events flow between instances server-side, with at-least-once delivery guarantees and full CloudEvents provenance tracking.

What is federation?

Without federation, each Kite instance is an island. A webhook received by Instance A is only visible to agents connected to Instance A. Federation breaks down these silos: when a peer relationship is registered, Instance A automatically forwards matching events to Instance B — and Instance B's listeners receive them just like any locally-ingested event.

Federation is implemented as a server-side hub. The Kite server handles all peer communication — no CLI or agent needs to be online for forwarding to succeed. Events are queued in a Postgres-backed outbox and retried with exponential backoff until delivered or dead-lettered.

Architecture

┌──────────────────┐                     ┌──────────────────┐
│  Kite Server A   │  federation_peers   │  Kite Server B   │
│                  │◄═══════════════════►│                  │
│  events table    │  mutual API keys    │  events table    │
│  federation      │  server-to-server   │  federation      │
│  outbox          │  HTTPS POST         │  outbox          │
└────────┬─────────┘                     └────────┬─────────┘
         │ WebSocket                              │ WebSocket
         ▼                                        ▼
    CLI / agents                            CLI / agents
    (Instance A)                            (Instance B)

Each server maintains a federation_peers registry. When an inbound event matches a peer's scope, the server enqueues an outbox entry. A background worker drains the outbox and POSTs events to the peer's inbound endpoint with HMAC authentication.

Event flow

1.Webhook arrives at Instance A → ingested, stored, broadcast to local listeners.

2.Server checks federation_peers for peers subscribed to this event's scope.

3.For each matching peer, an outbox entry is created (Postgres-backed).

4.Outbox worker POSTs the CloudEvent to the peer's /hooks/{team}/kite endpoint with HMAC auth.

5.Instance B ingests through its normal pipeline: signature verify, dedup, store, broadcast.

6.Delivery status is tracked in federation_deliveries for retry and observability.

CloudEvents provenance extensions

Every federated event carries three new CloudEvents extensions that form a provenance chain — recording where the event originated, which instances it traversed, and how many hops it has made.

Extension	Type	Description
`kitefedorigin`	string	Instance ID of the Kite server that first received the event.
`kitefedchain`	string (JSON array)	Ordered list of instance IDs the event has traversed.
`kitefedhops`	integer	Hop count. Incremented at each federation hop. Events exceeding max_hops are dropped.

Example federated event

{
  "specversion": "1.0",
  "type": "com.stripe.payment_intent.succeeded",
  "source": "https://a.kite.example.com",
  "id": "evt_abc123",
  "time": "2026-04-14T10:00:00Z",
  "kitefedorigin": "instance-a",
  "kitefedchain": "[\"instance-a\"]",
  "kitefedhops": 1,
  "data": { ... }
}

Loop detection

If your federation topology contains a cycle (A → B → A), events would amplify infinitely without protection. Kite prevents this with two mechanisms:

→Chain check: Before forwarding, the server checks whether the receiving instance's ID already appears in kitefedchain. If so, the event is dropped.
→Hop limit: Each peer has a configurable max_hops (default: 3). Events where kitefedhops reaches this limit are dropped and emitted as a kite.federation.delivery_failed internal event.

Agent-to-agent messaging

Federation enables a new structured event type for direct agent communication across instance boundaries:

{
  "type": "com.kite.agent.message",
  "source": "https://a.kite.example.com/agents/orchestrator",
  "data": {
    "to": "https://b.kite.example.com/agents/executor",
    "payload": { "task": "process_invoice", "invoiceId": "inv_xyz" }
  }
}

The com.kite.agent.message type is routed through the normal federation pipeline. Receiving agents can filter their listener to this type and handle cross-instance dispatching.

Security model

→Mutual authentication: Each peer relationship uses a pair of API keys — one for outbound, one for inbound. Neither instance accepts events without HMAC verification.

→TLS only: All server-to-server communication requires TLS. Cleartext federation endpoints are rejected at configuration time.

→Scope isolation: Peers are configured with explicit event scopes (e.g. stripe.*). Only matching events are forwarded — internal and out-of-scope events stay local.

→Team isolation: Federation is configured per-team. Events cannot cross team boundaries, even on the same Kite instance.

→Per-peer rate limits: Each peer has configurable rate limits to prevent a noisy upstream instance from impacting downstream delivery.

Next steps

→Getting started with federation →Federation API reference