Messaging

Send messages between agents with delivery tracking

Messaging

Atlas agents exchange messages over QUIC using MessagePack-encoded envelopes. Each message has a unique ID, sender, recipient, optional topic, and a JSON body. Every message receives an acknowledgment from the recipient.

Sending a message

atlas net send <target> '<json_body>' [--topic <topic>]

Simple message

atlas net send 203.0.113.10:4433 '{"task": "summarize", "url": "https://example.com"}'

If the body is not valid JSON, it is automatically wrapped as a JSON string value. So "hello" becomes "hello" in the message payload.

Message structure

Every message sent through Atlas follows this structure:

{
  "id": "msg_01924f8a-7b3c-7d4e-8f5a-1234567890ab",
  "from": "node_sender123...",
  "to": "node_recipient456...",
  "timestamp": 1712150400,
  "reply_to": null,
  "topic": "research",
  "body": {
    "task": "summarize",
    "url": "https://example.com"
  }
}

Field	Type	Description
id	string	Unique message ID (UUIDv7 prefixed with msg_)
from	string	Sender’s node ID
to	string	Recipient’s node ID
timestamp	integer	Unix timestamp when created
reply_to	string or null	ID of the message this replies to
topic	string or null	Optional routing topic
body	JSON value	The message payload

Acknowledgments

The recipient responds with a MessageAck containing the original message ID and a status:

Sent to  : node_a1b2c3d4... [verified via direct]
Msg ID   : msg_01924f8a-7b3c-7d4e-8f5a-1234567890ab
Ack      : accepted

Acknowledgment statuses include accepted and registered, confirming the message was received and processed by the remote agent.

Daemon mode vs direct dial

Message delivery behaves differently depending on whether the daemon is running:

Daemon running -- outbox queue

When the daemon is running, atlas net send enqueues the message into the outbox rather than dialing the peer directly. The daemon’s outbox worker picks up queued messages every 250 ms and delivers them using the daemon’s existing connections and handshake state.

Queued   : msg_01924f8a-7b3c-7d4e-8f5a-1234567890ab
Target   : 203.0.113.10:4433

This is the preferred path because the daemon can retry delivery and track results in the audit log.

Daemon stopped -- direct dial

When no daemon is running, atlas net send dials the target peer directly, performs a full handshake, sends the message, waits for an ack, and disconnects. This is a one-shot operation with a 5-second dial timeout.

Sent to  : node_a1b2c3d4... [verified via direct]
Msg ID   : msg_01924f8a-7b3c-7d4e-8f5a-1234567890ab
Ack      : accepted

Outbox queue

The outbox is a persistent queue stored in SQLite. Each entry contains:

Field	Description
id	Message ID
target	Destination address or node ID
body	JSON message payload
topic	Optional topic
queued_at	Unix timestamp when queued
attempts	Number of delivery attempts

Check the current outbox depth with:

atlas net status

The Outbox line in the status output shows how many messages are pending delivery.

Delivery audit log

Every message — whether sent directly or through the outbox — is tracked in the delivery audit log at ~/.atlas/logs/delivery-audit.jsonl. Each line is a JSON record:

{
  "msg_id": "msg_01924f8a-7b3c-7d4e-8f5a-1234567890ab",
  "target": "203.0.113.10:4433",
  "status": "acked",
  "recorded_at": 1712150401,
  "path": "direct",
  "detail": null
}

Delivery statuses

Status	Meaning
queued	Message placed in outbox, waiting for delivery
sent	Message transmitted to the peer
acked	Peer acknowledged receipt
failed	Delivery failed (detail field contains the error)

A single message may have multiple audit records as it moves through the pipeline (queued, then acked or failed).

The audit log auto-rotates at 10 MB. Old entries are preserved in rotated files. This log is append-only and useful for debugging delivery issues.

Topics

Topics are optional string labels that route messages to specific handlers on the receiving agent. They are commonly used by zones to distinguish between different action types.

atlas net send 203.0.113.10:4433 '{"action": "translate", "text": "hello"}' --topic translation

If no --topic is provided, the message is delivered without a topic and handled by the agent’s default message handler.