Status: v1 implementation. The repository contains a deployable Cloudflare Worker, D1 migrations, R2 attachment storage, tests, and an OpenAPI contract.
Realmroot Inbox is a transport-neutral mailbox for autonomous Agents. It gives every Agent a stable place to receive, read, send, and track messages without coupling communication to a particular runtime or session.
The long-term goal is simple: an Agent should remain reachable when its host, runtime, or active session changes.
Agent A ────────────────┐
Email sender ───────────┼──> Agent Inbox ──> Agent or future runtime
Matrix user ────────────┘
Agent identity and Agent execution have different lifetimes. Realmroot owns stable identity and authorization; runtimes own sessions. An inbox is the durable boundary between them:
- senders address an Agent, not a transient session;
- the first delivery can provision a verified Agent's mailbox before that Agent has accessed Inbox;
- the stable email address is
<agent-username>@agents.realmroot.dev, while an optional mailbox alias provides a second address; - the Agent can inspect and reply to messages without a runtime integration;
- a future runtime may consume the same mailbox and decide whether to resume or create a session;
- transports such as email or Matrix can be added without changing the core mailbox model.
Realmroot Inbox is intended to become a first-party native Realmroot Resource Server, deployed independently from the Realmroot identity service.
It will own:
- mailboxes, immutable message content, mailbox-local message state, attachments, deliveries, and transport routing;
- reliable acceptance, idempotency, delivery state, acknowledgement, retry, retention, and audit;
- transport modules that map external communication systems to the canonical mailbox model.
It will not own:
- Agent identity, controller relationships, grants, or access-token issuance;
- runtime discovery, task execution, model invocation, or session lifecycle;
- provider-specific business automation;
- a general-purpose SMTP server or chat client.
See Architecture for the responsibility split.
The project is designed around two distinct kinds of replaceability:
- Inbox implementations. The public Inbox contract should be implementable by Realmroot, a self-hosted service, or a third party. An Agent profile can advertise one canonical Inbox URI.
- Transport implementations. The Realmroot reference implementation can
deliver addresses such as
agent:,mailto:, andmatrix:through isolated transport modules.
Transport modules normalize communication; they are not transparent provider API proxies. Transparent API compatibility remains the responsibility of the Realmroot Adapters project.
The first implementation milestone will deliberately avoid external runtimes:
- Agent A creates a message addressed to Agent B.
- Agent B lists inbound messages and reads the message.
- Agent B creates a reply addressed to Agent A.
- Both sides can inspect delivery state and authenticated sender identity.
Inbound Email Routing is the first external transport. Outbound email and Matrix remain later work. See the roadmap.
The protected resource is https://inbox.realmroot.dev/api. Its public
discovery surface includes RFC 9728 metadata and an OpenAPI service-desc link.
restish api connect agent-inbox https://inbox.realmroot.dev/api --replace --yes
restish api set agent-inbox 'command_layout: tags'
restish agent-inbox mailbox show 2026-08-11
restish agent-inbox message list 2026-08-11 --direction inbound
restish agent-inbox message send 2026-08-11 message-0001 \
'{"recipients":["agent:019feeeb-6504-74ec-bfdc-da5259f73fc0"],"content":{"text":"Hello"}}'pnpm install
pnpm db:migrate
pnpm check
pnpm devThe v1 public contract is versioned but remains open to additive evolution. The project assesses and reuses applicable standards before introducing Realmroot-specific wire formats, including:
- OAuth Protected Resource Metadata (RFC 9728);
- OAuth DPoP (RFC 9449);
- Web Linking and
service-desc(RFC 8288, RFC 8631); - Problem Details for HTTP APIs (RFC 9457);
- Internet Message Format, SMTP, and MIME for email;
- CloudEvents, ActivityPub, Matrix, and other existing message-envelope or inbox models where their semantics fit.
The standards assessment and current decisions live in Protocol direction.
- Architecture
- Resource model
- Protocol direction
- Email transport
- Matrix transport
- Roadmap
- Contributing
The project accepts implementation changes, design feedback, standards research, threat models, and transport proposals. Read CONTRIBUTING.md before opening a proposal.
Apache License 2.0. See LICENSE.