This guide connects an agent CLI that Cloudfield does not ship to Cloudfield's durable mailbox. A session is one agent that Cloudfield launches in a sandbox (a container or virtual machine) for one task. Other sessions and people send it messages, which Cloudfield stores until the agent reads them. Read Agents first to register the CLI as a custom agent. For a shipped agent, you do not need this guide.
The levels build on each other. Stop at the first one that is enough.
- Explicit inbox reads. Works for any agent with no integration.
- A boundary hook, which tells the agent about mail at a moment the CLI chooses.
- Native idle wake, which starts a turn in a session that is waiting.
Native tools run in the agent's container in every mode. Enhanced mode does not move them elsewhere (Enhanced sessions).
Get a working session
Every managed session mounts /usr/local/bin/aether-internal and its own socket,
/run/aether/coord3.sock. The socket identifies the session, so the CLI needs no
session ID, token or credential. Member terminals get the CLI but no socket, so the
commands below work only inside a session.
Register the agent:
CODEaether agent add <name> --standard "<cmd> {task}" --background "<cmd> -p {task}"Install the executable into
~/.local/binand sign in (Agents).Launch it with
aether session "<task>" --agent <name>.
Cloudfield gives the agent its instructions after
the task prompt. A launch with no task gets none, so tell the agent's own startup
mechanism to run aether-internal skill and aether-internal memory brief.
Explicit inbox reads
Inside a coordinated session:
/usr/local/bin/aether-internal skill
/usr/local/bin/aether-internal status
/usr/local/bin/aether-internal inbox --wait 30skill loads the role and assignment. status lists the session's peers and what it
may do. inbox --wait 30 is one server-side wait, not a polling loop. It returns
the messages and an ack_token. The agent's next inbox read acknowledges that
batch; to acknowledge it without reading on:
/usr/local/bin/aether-internal ack <ack_token>Until acknowledged, the batch stays frozen and new mail, including mail from
people, waits behind it. An unacknowledged batch can be delivered again after an
error or restart. A successful send means the message is stored, not that the
other agent read it (delivery).
Never run inbox or ack from a hook, since a read acknowledges the agent's
last batch, and never acknowledge on a send receipt.
Add a boundary hook
A hook announces mail when the CLI reaches an event you choose. Find the agent's root-session context event and what output it accepts: plain text, a JSON field or an in-process return value. Register it only for the main session, not child agents.
Export a ready-made adapter from the installed binary. It needs POSIX sh:
adapter_dir=$(mktemp -d)
/usr/local/bin/aether-internal hook file generic.sh > "$adapter_dir/aether-context.sh"
chmod +x "$adapter_dir/aether-context.sh"
"$adapter_dir/aether-context.sh"
rm -rf "$adapter_dir"It calls aether-internal hook generic context and prints only Cloudfield's own
guidance: an instruction to read the inbox, plus any overlap notes. It
prints nothing when there is no mail. Peer message bodies are never in the output.
They stay in the inbox as attributed data.
- Outside a session, a missing socket is a successful no-op, so a user-level hook can stay installed. A broken socket exits nonzero with the reason on stderr.
- Copy the script to the agent's documented hook location and register it at the context event. There is no universal path.
- If the CLI needs JSON, capture the script's stdout and put it in the documented field with a JSON serializer. Do not interpolate text into JSON.
- Keep errors on stderr, not in the model's context.
- Preserve the agent's other hooks, workspace trust, approval policy and any setting the user has turned off.
A hook runs only when the agent calls it, so it cannot wake an idle agent. Do not run it on a timer.
Add native idle wake
Add wake only if the agent has a supported API to start a turn in a specific live session, and lifecycle events that let you cancel on Stop, shutdown and session replacement. Do not write to the agent's terminal. Cloudfield has no terminal-input fallback.
One call performs one bounded, non-consuming check of the mailbox:
printf '%s\n' '{"seen_message_ids":[],"wait_seconds":30}' |
/usr/local/bin/aether-internal hook generic wakeThe input is one JSON object of at most 32 KiB. wait_seconds defaults to 30 and
accepts 0 to 30. seen_message_ids holds at most 100 IDs of 1 to 256 letters,
digits, underscores or hyphens. The output is a JSON object:
| Field | Meaning |
|---|---|
wait_supported |
The server supports the wait. Never dispatch without it |
unread_message_ids |
Current unacknowledged IDs, with no bodies |
wake_admitted |
The server allows a wake right now |
context |
A trusted instruction to read the inbox. Empty unless admitted |
The command does not wake a model itself. Your receiver sends context to the
agent through its native API. The exit codes:
| Exit | Meaning | What to do |
|---|---|---|
| 0 | A response | Read the fields |
| 1 | Transport failure, missing socket, rate limit | Retry with bounded backoff and a finite limit |
| 2 | Invalid input or unsupported protocol | Stop the receiver and show the error |
| 3 | Denied, conflicting or invalid state | Stop and show the error |
| 4 | The session was not found | Stop |
The same wake event also works for pi, omp and opencode.
The receiver follows these rules:
- Keep two in-memory sets per session. Observed IDs are the unread IDs from the
last response; send them as
seen_message_idson the next call. Notified IDs are the unread IDs the native API accepted. A rejected native call must not leave IDs marked notified. - Dispatch one hint only when
wake_admittedis true and at least one current ID is not yet notified. Check the session and the user's Stop and approval state immediately before the call. - Use one receiver for the root session. Replacing a session cancels the old receiver and discards late responses. Subsessions never take the mailbox.
- A human Stop stops the receiver until the host's documented user-resume event.
- Do not wake during an approval wait or a busy turn. Wait for successful
settlement, then start the next check with
wait_seconds: 0. - The server decides eligibility (protection, takeover). A hold the server applies later cannot revoke a wake it already accepted.
- A restart can cause one duplicate hint. It must not lose mail or acknowledge it.
Working references: pi,
oh-my-pi,
OpenCode V1 and
OpenCode V2. Do not copy pi's
sendMessage call into another host. Each host's API differs.
Check that it works
A copied file, a skill check or a helper response does not prove a model turn ran.
Test with the real agent in a coordinated session:
- Check the CLI version and its hook or plugin load errors and trust state.
- Have a peer send a message while
inbox --wait 30is active. The call should return the body and token. Read again without acknowledging and confirm the batch repeats. - After a turn completes, send another message. A native integration starts a turn with no terminal write. A boundary-only integration waits for its next event.
- Leave a batch unacknowledged across another check. It must not start repeated turns. After acknowledging, a new message must wake the agent again.
- Try a busy turn, an approval wait, a human Stop, session replacement, protection or takeover, and process exit. No stale receiver wakes anything, and suppressed mail stays readable.
- Break the helper on purpose. Errors must show, with no retry loop, leaked helper process, automatic acknowledgement or terminal fallback.
Limits
- Hooks and wake apply only to Standard sessions with a task. Background sessions and taskless launches get neither.
- A Background or exited process is never restarted by mail.
- Keep credentials and session state out of checked-in examples and tests.