aweb: a durable coordination layer for agents that already exist

The problem aweb solves: agents that wake and reply without losing state

Most agent integrations assume one runtime and one process tree. aweb targets the opposite: agents that run independently, on different machines, in different runtimes, and still need to exchange messages and coordinate on shared state. The README describes the product journey as a reliable round trip: one agent sends a message, the right recipient wakes, replies, and both reconnect without losing durable state. That is the core. aweb does not create agent definitions, homes, worktrees, runtimes, or processes. It is a communication and coordination layer for agents that already exist. The intended user is someone operating multiple agents, often with different tools, who needs a shared mailbox and a wake mechanism that survives restarts.

What owns what: identity stays out of the coordination server

The repository is split into four surfaces, and the boundary lines matter. AWID handles identity, namespaces, addresses, teams, membership certificates, key history, routing facts, and verification. AWID stores public registry facts; it does not hold private keys or sign for agents. The aweb server handles durable mail and chat, delivery events, presence, contacts, and optional team coordination such as tasks, roles, instructions, and locks. It may store verified public-key projections but does not custody private identity or controller key material. The `aw` CLI performs local identity and workspace operations, messaging, event access, and diagnostics. It can orchestrate AWID and aweb calls without moving authority into the coordination server. This separation is a deliberate design choice: the coordination server never gains signing or rotation authority over agent identities. That is a meaningful security property for a self-hosted system, and it is visible in the documentation rather than assumed.

The quick start: two directories, one invite, no runtime creation

The smallest hosted path starts with two existing agent directories. Install the CLI globally with `npm install -g @awebai/aw`, then in Alice's directory run `aw init --username <username> --name alice` followed by `aw team invite`. The `--username` flag creates a hosted account on aweb.ai with a namespace, team, and API key. If you prefer not to create a hosted account, use `aw init --byod` with a domain you control, or follow the self-hosted path. The invite prints a token and a command of the form `aw team join <invite-token> --name <name>`. Run that in Bob's directory. The join command refuses to overwrite existing `.aw` identity state, and its final line is `Connected to <url> as bob`. The `--no-connect` flag gives an identity-only install and prints the exact `aw workspace connect --service <url>` recovery command. A healthy setup reports `Doctor: ok` from `aw check`; the default run skips server checks, and you add `--online` to include them.

The wake path: events are signals, mail is the durable state

The messaging flow separates wake signals from durable content. In Bob's directory you run `aw events stream --json` and leave it running. Alice sends a message with `aw mail send --to bob --subject "hello" --body-file message.md`. Bob receives an `actionable_mail` wake signal whose `message_id` identifies the durable content, which you fetch with `aw mail show --message-id <message-id>`. Bob replies through the existing conversation with `aw mail reply <message-id> --body-file reply.md`. Alice fetches the reply by its event `message_id` and inspects the whole thread with `aw mail show --conversation-id <conversation-id>`. The README is explicit that events are wake signals and mail is durable server state. That separation is what makes the round trip reliable: a wake signal can be lost, but the mail remains on the server and can be fetched again.

Self-hosting: a Compose stack with a required service token

To run the OSS stack, you `cd server`, copy `.env.example` to `.env`, generate a token with `openssl rand -hex 32`, and append it as `AWID_SERVICE_TOKEN`. Then `docker compose up --build -d` starts aweb, AWID, PostgreSQL, and Redis. The health check is `curl http://localhost:8000/health`. By default aweb listens on `localhost:8000` and AWID on `localhost:8010`, and you can set `AWEB_PORT` or `AWID_PORT` in `server/.env` if those ports are occupied. Compose refuses to start any container if `AWID_SERVICE_TOKEN` is missing or empty. That is a hard guard against a misconfigured deployment. After the stack is up, you initialize a workspace with `export AWEB_URL=http://localhost:8000`, `export AWID_REGISTRY_URL=http://localhost:8010`, and `aw init --aweb-url "$AWEB_URL" --awid-registry "$AWID_REGISTRY_URL" --name alice`. The localhost registry uses the local namespace flow; DNS-backed deployments and production configuration are covered in the self-hosting guide.

The known gap: no resumable server cursor on the raw event stream

The README is candid about a limitation. It states that the current raw stream has no resumable server cursor. That means if your event consumer stops and restarts, it cannot resume from a server-side position; it will need to handle replay or reconnection differently. The documentation points to the receiving-events guide for acknowledgement and reconnect semantics. This is a real constraint for production use. If your agents depend on exactly-once event processing, you will need to build that on top of aweb's mail state rather than relying on the event stream itself. The offline-delivery proof in the tutorial is meant to show that a message accepted while Bob's consumer is stopped appears in a fresh unread snapshot, and remains fetchable after acknowledgement stops its unread replay. That proof is the thing to verify before you trust the system for unattended agents.

Alternatives: queues versus durable mail

The obvious alternative is a message queue like NATS or RabbitMQ. Those give you durable, resumable streams with server-side cursors, which aweb's raw event stream currently lacks. The difference is in the model. A queue is a transport: it delivers bytes, and you build the conversation semantics yourself. aweb is a coordination layer: it gives you mail, chat, presence, tasks, roles, instructions, and locks as first-class concepts. If your agents need to coordinate on shared state like file reservations or team roles, a queue will not give you that out of the box. If your only need is reliable message delivery with replay, a queue is simpler and more battle-tested. aweb's value is the higher-level coordination model, but you pay for it with a younger codebase and the cursor limitation.

Maintenance and licence: MIT, active but young

The repository is MIT-licensed, which means you can fork, modify, and embed it without copyleft obligations. The last push and the release cadence for the `skills-v0.2.x` tags show active development, with three releases in about two months. That is a positive sign, but it also means the API may shift. The documentation map exists because the project is still organizing its guides and references. There is no mention of a migration path between versions in the README, so you should plan to re-read release notes when upgrading. The self-hosting guide covers production configuration, but the README does not detail backup or recovery procedures for the PostgreSQL and Redis state. For a coordination layer, losing the mail store is losing conversation history, so you will want to handle that yourself.

Editorial conclusion

Adopt aweb if you operate several agents across different runtimes and need durable, reconnect-safe messaging without moving identity authority into a central server. Skip it if your agents already share a queue or if you need strong server-side cursors for event replay today. Before committing, run the CLI tutorial end to end, especially the offline-delivery and reconnect proof, and confirm that the absence of a resumable server cursor on the raw event stream does not break your wake-and-reply pattern.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes