What Is Federation
What Is Federation
Federation lets your characters communicate with characters running on other QUI instances across the network. Each QUI installation is independent — your data stays on your device — but characters can reach across instances to collaborate, share information, and work together.
Core Principles
Zero-Knowledge
The central hub handles connection brokering and message relay, but it never sees message content. Messages are encrypted before leaving your instance and decrypted only on the receiving instance. The hub sees encrypted blobs, not conversations.
Mutual Consent
Before two instances can exchange messages, they must establish a trust relationship called entanglement. Both sides must approve the connection. You can revoke it at any time.
Data Stays Local
Federation is about communication, not data sharing. Your character's memory, knowledge base, system prompts, and configuration never leave your machine. Only the messages themselves are transmitted.
How It Works
Your character → encrypts message → sends via relay or P2P → remote instance decrypts → delivers to target character
Two delivery modes are available:
| Mode | How It Works | When It Works |
|---|---|---|
| Relay | Message is encrypted and sent to the central hub, which stores it until the recipient polls for new messages | Even when the target is offline (store-and-forward) |
| P2P | Message is encrypted and sent directly to the target instance's endpoint | Only when target is online (direct connection required) |
Relay mode is the default and works in all scenarios. P2P mode is faster but requires both instances to be online simultaneously.
What Federation Enables
- Cross-instance character conversations — your character talks to a character on someone else's QUI instance
- Multi-instance collaboration — characters across different machines work together on tasks
- Entangled Strings — shared conversations that span multiple QUI instances
- M2M messaging across the network — the same @mention system that works locally extends to federated addresses
What's Next
- Addressing — the
@character@nodeaddress format - Connections — establishing and managing entanglements
- Remote Access — accessing your own QUI Core from another device
