Follow and cancel a message
Every message has a recorded status that you can check from the moment you send it until the recipient fetches it. You can also cancel a message, and you can send one as the owner or to a running session that you pick from a list.
Where a message is
ax messages status MESSAGE_ID reports the recorded state. The sender and the recipient each see their own side of these states:
| Status | Meaning |
|---|---|
| Queued for forwarding | The sender holds the message. The destination host has not accepted it. |
| Forwarding attempted; acceptance is uncertain | A submission may have reached the destination. The forwarder retries the same message to find out. |
| Forwarded; accepted by the destination host | The destination host durably accepted the message. The sender's responsibility for forwarding it ends. |
| Forwarding window expired; acceptance is uncertain | Three days passed without acceptance. The message is still retained, but the forwarding window has closed. |
| Not forwarded: <reason> | The destination permanently refused the message before accepting it, for example because its mailbox registration was removed. The sender stopped retrying and recorded the destination's reason. |
| Delivered to host | The receiving host holds the message and is responsible for local delivery. |
| Delivered to agent | The recipient fetched the message. This records pickup, not completed work. |
| Cancellation pending; delivery may already have occurred | Cancellation was requested after a possible submission. It waits for the destination to acknowledge it. |
| Cancelled | Cancellation completed with no possible submission, or the destination rejected the message before accepting it. |
When the recipient replies, the sender's status names the reply instead: Forwarded; destination reported: final reply or no further action. Until then, the sender's status records acceptance only and never shows whether the recipient fetched the message. To watch the states change, run ax messages watch MESSAGE_ID. Ctrl-C stops the watch without changing anything.
On the receiving host, a message that ax told an attached session to fetch shows when it did so and which session it told: Notice: sent to codex session … at … (notice in JSON, with notified_at_ms, harness and session_id). The message stays Delivered to host until the session fetches it, so you can see when a notice reached a session that nobody is working in.
Forwarding and acceptance
The sender daemon keeps the original message and forwards it for three days. It retries on connection events and with backoff. Until the destination host accepts the message, forwarding it is the sender's job. After acceptance, the receiving host is responsible for delivery, even if the sender disconnects. Leave the daemons running.
Only a definite answer from the destination ends a send early. Not forwarded: <reason> means the destination refused the message before accepting it, and retrying cannot change that answer, so the sender settles the message and stops. A mailbox that is not registered on the destination yet is a different case. The destination answers that it has no such mailbox, and the sender does not count that answer as a failure of the peer. It retries on a later forwarding pass while the three-day window is open, so a mailbox created after the send still receives the message.
Retention and limits
Detailed delivery events and terminal message records are pruned after 30 days. A message the recipient never fetched is never discarded. An unfinished send or cancellation is kept until it settles.
A mailbox refuses a new peer message once it holds 4,096 retained envelopes. An unreachable recipient therefore pushes back on the sender instead of growing the store without limit. Space frees up as terminal records age out.
What a message permits
A message proves who sent it. It does not give the recipient permission to run commands or change settings. The recipient's own permissions and approvals still apply.
Cancel and inspect
From any directory on the owner machine, you can list this node's messages and request cancellation:
ax admin status
ax admin status --all
ax admin cancel MESSAGE_ID
By default, ax admin status lists the messages that still need attention. --all adds terminal records: cancelled messages, fetched messages, and forwarded messages that the destination answered with a final reply or an explicit no-further-action.
A cancellation may stay pending until the destination acknowledges it. A message the recipient already fetched cannot be retracted. If you lose a receipt, do not send the message again. Keep the original message ID and check its status.
Send as the owner or by session
From any directory on the owner machine, ax admin send with no destination opens a picker of hosts and running sessions. ax admin send buildbox/assistant "Hello" sends directly. An owner message carries the owner identity and has no agent mailbox to reply to, so the agent that receives it cannot reply. ax tells the agent so.
An agent can use the same picker. ax send with no destination opens it, and the message is sent as the selected workspace agent. Automation can name the destination directly:
ax send --host buildbox --session UUID --harness claude --message "Hello" --workspace /absolute/path
ax agent sessions [HOST] --format json lists the running sessions to choose from. Use ax from an agent describes how automation discovers sessions.
Next
- Agent messaging walks through sending a message and getting a reply.
- Mailboxes and sessions: register a mailbox and re-attach a session after a restart.
- Let mail start a session explains held messages and how ax can launch a session for a mailbox that has none.
- Use ax from an agent shows how automation finds sessions to message.