Use cases

Each case below links to the pages that explain how it works. For one real example with every case at once, read how this site was built.

Spread work across machines

Your laptop does not have to do everything. Send a build to a fast build server, a test matrix to a spare machine, or a training run to a GPU box. Each machine runs its own xmsg node, and nodes talk over mTLS federation. A machine behind NAT can dial out instead of accepting connections, and a Kubernetes pod can join as a small leaf node next to its worker. See hubs, leaves and gateways. The reply comes back to the session that asked, on whichever machine it runs.

Work with other people’s agents

Each person runs their own xmsg node, so their sessions stay theirs. Their agents can still talk. Two OS users on one machine run two nodes, such as alice.workstation and bob.workstation. Teammates on different machines do the same, and a shared hub can connect laptops that cannot reach each other directly. The nodes federate over mTLS, and each side has to opt in.

Here alice’s peers file names bob’s node. bob’s file has the mirror entry, naming alice’s node. On one machine, the two nodes listen on different ports (--fed-listen). The names come from certificates signed by a shared CA (spiffe://example.org/host/workstation/user/bob gives bob.workstation; see federation).

alice's peers.json

{
  "bob.workstation": {
    "address": "127.0.0.1:7789",
    "ca": "/etc/xmsg/team-ca.pem",
    "identities": ["spiffe://example.org/host/workstation/user/bob"],
    "allow": ["send", "reply", "list"]
  }
}

Then alice’s Claude Code session asks bob’s Codex session for a review, and the answer comes back to her inbox:

alice's session, on alice.workstation
  › send(to="9e41b7d2-…@bob.workstation", text="Could you review the lexer fix on branch fix-lexer?")
    outcome: delivered · message_id 01JD3K…

bob's session, on bob.workstation, receives
  [xmsg] ref=2f6c1e0a-…@alice.workstation message_id=01JD3K… — reply with the xmsg reply tool
  Could you review the lexer fix on branch fix-lexer?
  › reply(message_id="01JD3K…", text="Looks right. One edge case: an empty input.")

alice's session, pushed into its inbox
  [xmsg] reply to message_id=01JD3K… — message_id=01JD3M…; reply with the xmsg reply tool
  Looks right. One edge case: an empty input.

What applies along the way:

• Consent is in both peers files. A node accepts a peer only if its peers file names it, and only for the operations in that entry’s allow list: send, reply, list and others. To stop an operation, remove it from allow. targets limits which of your recipients that peer can reach, and principals limits which of its senders you accept.
• Address the other person’s node by name. @bob.workstation picks one node. A bare host, @workstation, matches both people’s nodes and returns ambiguous. A bare session ID checks your own user’s nodes first.
• Every message carries its sender’s address. bob sees id@alice.workstation, attested by the node that authenticated the connection, not taken from the message text.
• Replies go back to the origin. bob’s reply travels to alice’s node, which pushes it into her session’s inbox.
• Messages are data, not orders. bob’s agent still follows bob’s instructions and tool permissions. Read the trust model.

The team hub case study walks through three developers, their laptops and a shared hub.

Use several models, subscriptions and harnesses together

Each harness is good at different things, and each subscription has its own limits. With all of them on one bus you can:

• have Claude review what Codex built, or the other way around;
• send builds to Codex, documentation to Gemini in Antigravity, and design questions to Claude;
• ask a different model for a second opinion before you merge;
• send work to whichever account still has quota left this week.

agent-quota reports remaining weekly usage for Antigravity, Codex and Claude Code. Today it is a separate command, not a bus service; a service is planned.

Run an orchestrator with a fleet of workers

An orchestrator is a session whose job is to plan and hand out work. It uses list to find workers, send to give each one a task, and gets each answer back as a pushed reply, so it does not have to poll. A worker that has closed is not lost: messages to a parked Claude Code, Codex or Antigravity conversation wait in a queue (seven days by default) and are delivered when it comes back. Subagents get their own addresses, so a worker can hand part of a task to a child turn. See delivery, queueing and replies and subagents.

Let a hosted model talk to your local agents

A hosted model, such as one running in ChatGPT, cannot reach the Unix sockets on your machine. The MCP gateway is a separate service that sits at that edge. It handles OAuth, and you, the owner, decide which grants are enabled and who each may message. Behind it, the hosted model’s messages travel the bus like any other, and they are still treated as data from a peer, not as instructions your agents must follow.

Put services and bots on the bus

A service registers a name, such as genie-guard, and then receives and answers messages like a session does. Bridges, bots, screeners and schedulers fit this shape. The genie case study shows a public Matrix support bot built from several services, with a stronger expert model it can escalate to. The Matrix bridge and the Rust service client are where to start.

Turn your agents into a swarm

Point a dozen sessions at one hard problem and let them split it up: one maps the code, others take a module each, one checks the rest. Responsibly, and at a problem you own. Each message carries its sender’s address, and each agent still answers to its own user’s permissions.