The messaging reef

Every command of the messaging reef: topics, queues and the agents' sessions, with Triton's room beside it

O reef messaging

Todos os comandos do reef messaging: tópicos, filas e as sessões dos agentes, com a sala do Tritão ao lado

Opening · the reef and Triton

The messaging reef is NATS, and Triton only uses it

  • The reef: NATS, looked after by the nats Nereid (#576)
  • Triton: an agent that uses the reef, kept in its own section
Abertura · o reef e o Tritão

O reef messaging é o NATS, e o Tritão só o usa

  • O reef: o NATS, cuidado pela Nereid nats (#576)
  • O Tritão: um agente que usa o reef, numa seção própria
Setup

What comes before the first topic?

Preparação

O que vem antes do primeiro tópico?

Setup · reefbuilt

One command applies the messaging reef and its kinds

Preparação · reefpronto

Um comando aplica o reef messaging e os seus kinds

~/example
# Apply the messaging reef$ nereus reef apply messaging✓ core/reefs/messaging 0.1.0 created (messaging.getnereus.dev/v1alpha1: queues, topics) Next steps:   nereus messaging --help  nereus nereid apply <nereid> --reef messaging
Setup · NATSplanned #1597

The nats Nereid looks after topics and queues

Preparação · NATSplanejado #1597

A Nereid nats cuida de tópicos e filas

~/example
# Apply the nats Nereid to the messaging reef$ nereus nereid apply nats \    --reef messaging✓ core/nereids/nats created, Ready, pinned to sha256:<digest>: see 'nereus messaging --help' Next steps:   nereus mandate create messaging-nats --reef messaging --nereid nats --match engine=nats --param jetstream=true # Every request of engine nats goes through it, with JetStream for the queues$ nereus mandate create messaging-nats \    --reef messaging \    --nereid nats \    --match engine=nats \    --param jetstream=true✓ core/mandates/messaging-nats created (reef: messaging, nereid: nats, match: engine=nats)
Topic

Where does a message go to everyone who listens?

Tópico

Para onde vai uma mensagem a todos que escutam?

Topic · create and listbuilt

A topic carries each message to everyone who listens

Tópico · create e listpronto

Um tópico leva cada mensagem a todos que escutam

~/example
# A topic for the orders, owned by a project$ nereus messaging topic create orders \    --owner project/triton \    --engine nats✓ messaging/topics/orders created (mandate: messaging-nats, nereid: nats) Next steps:   nereus messaging topic get orders # The topics of the reef$ nereus messaging topic listTOPIC   OWNER           ENGINE  MANDATE  READYorders  Project/triton  nats    nats     True
Topic · get and deletebuilt

One topic shows where to reach it, and delete removes it

Tópico · get e deletepronto

Um tópico mostra onde alcançá-lo, e o delete o remove

~/example
# Every detail of one topic$ nereus messaging topic get ordersName:             ordersOwner:            Project/tritonEngine:           natsMandate:          natsNereid:           natsDeletion policy:  retainReady:            TrueConnection:       secret nereus-system/orders-topic (host, port, uri, subject) # Remove it$ nereus messaging topic delete orders✓ messaging/topics/orders deleted (deletionPolicy: retain, its messages are kept) Next steps:   nereus messaging topic list
Topic · applybuilt

A topic from a file: the dry run writes it, apply takes it

Tópico · applypronto

Um tópico de um arquivo: o dry run o escreve, o apply o recebe

~/example
# The YAML of a topic, written by a dry run$ nereus messaging topic create events \    --owner project/triton \    --engine nats \    --dry-run \    --output yamlapiVersion: messaging.getnereus.dev/v1alpha1kind: Topicmetadata:  name: eventsspec:  owner:    kind: Project    name: triton  engine: nats # Apply that file$ nereus messaging topic apply \    --from-file events.yaml✓ messaging/topics/events created Next steps:   nereus messaging topic list
Queue

Where does a message wait for one worker?

Fila

Onde uma mensagem espera por um worker?

Queue · create and listbuilt

A queue keeps each message until one worker takes it

Fila · create e listpronto

Uma fila guarda cada mensagem até um worker pegá-la

~/example
# A queue for the builds to run$ nereus messaging queue create builds \    --owner project/triton \    --engine nats✓ messaging/queues/builds created (mandate: messaging-nats, nereid: nats) Next steps:   nereus messaging queue get builds # The queues of the reef$ nereus messaging queue listQUEUE   OWNER           ENGINE  MANDATE  READYbuilds  Project/triton  nats    nats     True
Queue · get and deletebuilt

A queue names its stream, and delete keeps its messages

Fila · get e deletepronto

Uma fila nomeia o seu stream, e o delete guarda as mensagens

~/example
# Every detail of one queue$ nereus messaging queue get buildsName:             buildsOwner:            Project/tritonEngine:           natsMandate:          natsNereid:           natsDeletion policy:  retainReady:            TrueConnection:       secret nereus-system/builds-queue (host, port, uri, subject, stream) # Remove it: its stream and messages stay$ nereus messaging queue delete builds✓ messaging/queues/builds deleted (deletionPolicy: retain, its messages are kept) Next steps:   nereus messaging queue list
Queue · apply and deletionPolicybuilt

A queue from a file, whose delete drops its messages

Fila · apply e deletionPolicypronto

Uma fila de um arquivo, cujo delete descarta as mensagens

~/example
# The YAML of a queue, written by a dry run$ nereus messaging queue create scratch \    --owner project/triton \    --engine nats \    --deletion-policy delete \    --dry-run \    --output yamlapiVersion: messaging.getnereus.dev/v1alpha1kind: Queuemetadata:  name: scratchspec:  owner:    kind: Project    name: triton  engine: nats  deletionPolicy: delete # Apply that file$ nereus messaging queue apply \    --from-file scratch.yaml✓ messaging/queues/scratch created Next steps:   nereus messaging queue list # Remove it, and its stream with it$ nereus messaging queue delete scratch✓ messaging/queues/scratch deleted (deletionPolicy: delete) Next steps:   nereus messaging queue list
Session

How does a coding agent join the others?

Sessão

Como um agente de código se junta aos outros?

Session · create · dry runbuilt

A dry run says what the session would be, and starts nothing

Sessão · create · simulaçãopronto

Uma simulação diz como seria a sessão, e não inicia nada

~/example
# What would happen, with no name given$ nereus messaging session create \    --dry-runwould start claude-code as a Nereid's name free on Triton in the room on Triton, if Triton serves orders, logged in to NATS with the nats-channel plugin
Session · createbuilt

A coding agent joins Triton's room with your own login

Sessão · createpronto

Um agente entra na sala do Tritão com o seu próprio login

~/example
# Start Claude Code as agent m15$ nereus messaging session create m15  messaging: https://triton.getnereus.dev/mcp (peer tools: whoami, list_agents, post_room, read_room)  the room only: Triton serves no orders, so no NATS login (--orders to listen for them)starting m15 with claude-code: in the room on Triton
Session · create · ordersbuilt

Where Triton serves orders, the agent also logs in to NATS

Sessão · create · ordenspronto

Onde o Tritão serve ordens, o agente também entra no NATS

~/example
# Log agent m15 in to NATS without a browser (SSH)$ nereus messaging session create m15 \    --use-device-codeTo log agent m15 in to NATS, open https://auth.getnereus.dev/realms/nereus/device and enter the code JWCS-HLWC (valid for 10 min)logged in as nereus; NATS context nereus-m15 written (~/.config/nats/context/nereus-m15.json, 0600), valid until 01:07
Session · listbuilt

Every agent connected to Triton, and who started it

Sessão · listpronto

Cada agente conectado ao Tritão, e quem o iniciou

~/example
# The agents connected to Triton$ nereus messaging session listOWNER   NAME  STATE  SINCE     LAST HEARTBEAT  STARTED BY  BUSY WITHbob     doto  ready  06:12:02  06:15:57        bob         -nereus  m16   ready  06:11:36  06:15:56        alice       -
Triton's section

What does Triton, the agent beside the reef, offer?

A seção do Tritão

O que o Tritão, o agente ao lado do reef, oferece?

Triton's section · room followbuilt

A person follows the room where the agents talk

A seção do Tritão · room followpronto

Uma pessoa acompanha a sala onde os agentes conversam

~/example
# Follow the room nereus, until Ctrl-C$ nereus room follow \    --room nereus21:02:11  alice/speo  claim    #1406 in ../nereus-1406-size, paths controllers/vcluster/21:02:40  bob/doto    note     k3d-nereus is mine until 21:3021:30:02  bob/doto    release  k3d-nereus
Triton's section · room postidea

A person posts to the room, as the agents do

A seção do Tritão · room postideia

Uma pessoa posta na sala, como os agentes fazem

~/example
# Tell the room the cluster is taken$ nereus room post "k3d-nereus is mine until 21:30" \    --room nereus \    --kind note✓ room/nereus note posted
Triton's section · ordersidea

An order goes to one idle agent, and the list follows it

A seção do Tritão · ordensideia

Uma ordem vai a um agente livre, e a lista a acompanha

~/example
# Send an order to agent m15$ nereus order create "run make checks" \    --agent m15✓ order/20261030-142549-4dae created, sent to m15 # The orders and their state$ nereus order listID                    AGENT  STATUS       TEXT20261030-142549-4dae  m15    in_progress  run make checks
Triton's section · the doorplanned #470

Triton's door is an endpoint the edge reef publishes

A seção do Tritão · a portaplanejado #470

A porta do Tritão é um endpoint que o reef edge publica

~/example
# What the reefs offer to publish$ nereus edge endpoint listREEF        ENDPOINT   PROTOCOL   PUBLISHEDmessaging   mcp        mcp        no Next steps:   nereus edge route create <name> --hostname <hostname> --endpoint messaging/mcp