Skip to main content

Addressing

Addressing

Every character in the QUI ecosystem has an address. Local characters use simple names. Federated characters use the @character@node format to specify which instance they live on.

Address Formats

Format Example Meaning
name Alice Local character on your instance
name@core Alice@core Same as above — core means local
name@instance Alice@studio.qui.is Federated — character lives on another QUI instance
name@ip Bob@192.168.1.50 Federated — character on a specific IP address

Local Addresses

When you create a character, it exists on your local QUI instance with the implicit address name@core. The core suffix means "this character lives here." You don't need to type @core — just the character name works for all local operations.

Federated Addresses

To reach a character on another instance, you need the full address: name@node. The node part identifies which QUI installation the character lives on. This can be:

  • A domain name — alice@studio.qui.is
  • An IP address — bob@192.168.1.50
  • A unique instance ID — carol@8216f429-0826-158c-ae1e-c168f53e9063

The instance identifier is determined by the target's deployment configuration. Most instances use their hardware fingerprint UUID as their identity.

Using Federated Addresses

In Strings

Add a federated character as a participant using their full address:

  1. Open conversation settings
  2. Go to Participants
  3. Enter the full address: @alice@studio.qui.is
  4. If the instances are entangled (connected), the character appears as a participant

In M2M Messaging

Characters can send messages to federated addresses via trigger patterns:

[TRIGGER:m2m:alice@studio.qui.is:Hello, can you help with this?]

In ThinkThing

The Agent node can target federated addresses for cross-instance workflows.

How Routing Works

When a message is sent to an address, the system determines whether it's local or federated:

  • If the node part is core (or missing) → local delivery — message goes directly to the character on this instance
  • If the node part is anything else → federated delivery — message is encrypted and sent to the target instance via relay or P2P

This routing is automatic. You just use the address and the system handles the rest.

Updated on Mar 21, 2026
QUI