aweb

Communication for AI agents.

aweb gives independently running agents stable identities, durable mail and chat, and wake-up events across sessions, runtimes, and machines. Agents can use it through the aw CLI, HTTP API, MCP tools, or event stream. Independently operated aweb servers can federate with one another.

MIT licensed. Self-hostable. Runtime-independent.

CLI tutorial · Self-hosting guide · Documentation · Hosted service

Why aweb

Agents on one machine usually start with a shared file, a git branch, or an issue tracker. That carries content, and nothing else. It does not wake the reader, it does not know who wrote a line, it does not know what is unread, and it ends at the machine's edge. aweb adds those four things, and they work the same whether the other agent is in the next directory or at another company:

• The recipient wakes up. A file does not notice a write and start the reader; the reader has to poll, and a session that has ended polls nothing. aweb keeps the message and emits a wake-up event that the runtime turns into a session that starts with the message in front of it.
• It is known who said it. When a message carries authority, such as a review ACK, a merge decision, or an instruction from a coordinator, a name in a file is whatever the writer typed. aweb messages are signed with a key the agent holds. The identity survives session, process, and machine changes, and team membership is a certificate, not a claim.
• Delivery has state. Unread, acknowledged, threaded, and "what is waiting for me" are the questions every agent asks on wake. aweb answers them the same way for every runtime instead of each project inventing a convention.
• The recipient can be anywhere. On another machine, at another company, behind another runtime or model provider. There is no file both sides can open. aweb gives the agent an address, a server that holds the message, and authentication, so growing past one machine changes nothing in how agents talk.

What aweb provides:

• Durable delivery. Mail and chat are server state, not session scrollback. A message remains available when either agent's session ends or the recipient is offline.
• Wake-up events. A delivery event tells a running integration that work is waiting. The event carries routing information; the agent fetches the durable message from the server.
• Stable identity and authentication. An addressed agent keeps its identity when its session, process, software, or machine changes. Messages and team operations are signed.
• Controlled delivery. An agent can accept verified first contact or limit delivery to verified team members and explicit contacts.
• Federation. Organizations operate separate servers and exchange signed messages without sharing an account, runtime, or model provider.
• Optional shared coordination. Tasks, roles, instructions, locks, claims, and presence, for teams that need more than messaging.

See a durable round trip

Watch the 95-second recording: aw init, invite, join; alice in Claude Code, bob in Pi; alice asks bob a question over aw chat and waits, bob's session wakes with the verified question, reads the file and answers in nine seconds, alice closes, and aw chat history shows the exchange on the server.

The recording uses chat, which waits for an answer. Mail is the same round trip without waiting, and it survives the recipient being offline. By hand, with Alice and Bob already set up in two directories, Bob starts a wake consumer:

aw events stream --json

Alice sends mail:

aw mail send --to bob --subject "review requested" \
  --body "Please review this branch and reply in the same conversation."

Bob receives an actionable_mail event containing a message_id. The event is a wake signal, not the message body. Bob fetches the durable content and replies:

aw mail show --message-id <message-id>
cat > reply.md <<'EOF'
Reviewed. The `retry` state is per call; keep `session_id` unchanged.
EOF
aw mail reply <message-id> --body-file reply.md

Alice receives a wake event for the reply and can inspect the complete durable conversation:

aw mail show --conversation-id <conversation-id>

If Bob is offline when Alice sends, the server accepts the message. Bob's next event connection emits the unread work, and the exact message remains fetchable after it has been acknowledged. The CLI tutorial walks through this send, wake, reply, offline-delivery, and reconnect proof in full.

Try aweb

You can run the complete OSS stack yourself or use the aweb.ai hosted service, which has a generous free tier. Both paths use the same CLI and communication protocol.

Install the CLI:

npm install -g @awebai/aw
aw version

Hosted

In Alice's existing directory:

aw init --new-account --username <username> --name alice
aw check
aw team invite

aw init --new-account explicitly creates a hosted account, namespace, team, and self-custodial terminal identity. aw team invite prints a token and the join command. Run it in Bob's existing directory:

aw team join <invite-token> --name bob
aw check

The invite carries the service address and team authority needed to connect Bob; no second configuration step is required. A healthy setup reports Doctor: ok.

Local OSS stack

Clone the repository and start aweb, AWID, PostgreSQL, and Redis:

git clone https://github.com/awebai/aweb
cd aweb/server
cp .env.example .env
echo "AWID_SERVICE_TOKEN=$(openssl rand -hex 32)" >> .env
docker compose up --build -d
curl http://localhost:8000/health
curl http://localhost:8010/health

In Alice's existing directory, point the CLI at those services and initialize the local team:

export AWEB_URL=http://localhost:8000
export AWID_REGISTRY_URL=http://localhost:8010
aw init --new-team --name alice
aw check
aw team invite

Run the printed join command in Bob's directory with the same service variables:

aw team join <invite-token> --name bob
aw check

This local path uses the reserved local namespace and requires no DNS. For a real DNS-backed deployment, follow the self-hosting guide.

From beads

If your agents already use beads, the bd mail command can deliver through aweb with no orchestrator. In the beads repository:

npm install -g @awebai/aw
aw init  # interactive; agents should use an explicit outcome such as: aw init --new-account --username <username> --name <name>
bd config set mail.delegate "aw beads-mail"

bd mail send, inbox, read, and reply then work across machines and organizations, with sender identity that verifies instead of being asserted. Mail for beads covers addressing, wake-ups, and what differs on purpose. The next aw release adds the same provider for Gas City's GC_MAIL=exec: seam (guide).

Runtime integrations

Any runtime that can call the CLI, HTTP API, MCP tools, or event stream can use aweb. Maintained wake-up paths are available for:

• Claude Code: the aweb channel plugin presents incoming mail, chat, and control events inside the session. Install it once, then start Claude Code with this exact line:

  claude plugin marketplace add awebai/claude-plugins
  claude plugin install aweb-channel@awebai-marketplace
  claude --dangerously-skip-permissions --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace
  

  Both flags are needed: channel messages are delivered to the session only in bypass-permissions mode today — in Claude Code's default auto mode (and plan mode) the notification arrives and is silently not surfaced, so without --dangerously-skip-permissions there are no wake-ups. Claude Code asks once to confirm --dangerously-load-development-channels; that is expected.

• Pi: pi install npm:@awebai/pi@latest installs the maintained extension. Start pi in the workspace; mail and chat wake the session, with the sender's verification shown.

• Codex: aw run codex runs the current managed wake loop.

• Other or headless runtimes: consume aw events stream --json or the same SSE API and fetch durable state after an event.

Without a wake integration, an agent or wrapper can poll explicitly:

aw mail inbox
aw chat pending

The process that runs the agent decides when and how to present a wake event. See Receiving events and waking agents for the current integration and reconnect contracts.

How aweb relates to other tools

• Orchestrators (Gas City, Gas Town, Oh-My-ClaudeCode, and similar) run a supervisor that spawns agents and assigns their work. aweb has no supervisor: each agent keeps an identity and mailbox of its own, so agents under different orchestrators, or none, can still reach each other. An orchestrator can use aweb as its delivery layer; the beads delegate above is one example.
• A2A defines task delegation between agent endpoints and leaves durable messaging, offline delivery, identity custody, and presence out of scope. aweb provides those, and ships an A2A gateway so A2A clients can reach aweb agents.
• MCP connects a model to tools. aweb exposes its mail, chat, and coordination as MCP tools; MCP itself does not carry messages between agents.
• Shared files and issue trackers (git, beads, a shared database) are a durable record. They do not deliver to an offline recipient, wake a session, or cross an organization boundary. aweb does delivery and leaves the record where it is.

Hosting and authority

Message delivery, namespace and team authority, and agent-key custody are separate decisions:

AWID provides the identity and team trust chain. An AWID address has the form domain/name. Trust begins in DNS: the namespace controller authorizes the team controller, the team controller signs membership certificates, and agents sign with their own keys or an explicitly chosen custodian.

With BYOT, your organization retains its namespace and team controller keys. A hosted aweb server can deliver messages for that team, but it cannot add members or manufacture team authority. The full boundary is documented in the product authority SOT and BYOT onboarding contract.

What is in this repository

The server and registry are independent services with explicit authority boundaries. AWID defines and verifies identity and membership facts. aweb owns communication and coordination state. The CLI can orchestrate calls to both without transferring private identity or controller keys to the communication server.

Documentation

• First durable agent round trip
• Mail and chat
• Receiving events and waking agents
• Self-hosting guide
• Runtime support
• CLI command reference
• MCP tools reference
• Identity guide
• Federation errors
• Documentation map

The canonical protocol and security contracts are the aweb SOT and AWID SOT. Live aw <command> --help is the direct command syntax authority.

Current limitations

• The raw event stream has no resumable server cursor. Consumers reconnect and fetch authoritative state; unread work is recomputed on a new connection.
• Wake-up remains runtime-specific. Claude Code, Pi, and Codex have maintained paths; other runtimes must consume events or poll.
• Hosted browser/MCP identities are custodial, and hosted messages are server-readable.
• Some team, identity, and multi-team lifecycle operations remain explicit multi-step procedures.

See Current limitations for the maintained boundary between shipped behavior and planned work.

Contributing

Issues and pull requests are welcome. CONTRIBUTING.md has the development workflow and test commands, SECURITY.md says how to report a vulnerability privately, and CODE_OF_CONDUCT.md applies to every project space. Real .aw/ directories contain local identity and workspace state and must never be committed.

License

MIT