# Apron Chat Protocol

> Apron is a simple chat protocol that decouples clients from servers: use an existing client with your own backend, or build a new client for existing Apron servers. A basic server is about a hundred lines of code, and a stateless bot is a few.

Use Apron for a self-hosted group chat, an agent interface, or a bridge to another service. It is for small groups whose members mostly trust each other: a team, a household, or a set of bots and the people who run them. The server is trusted with identity, membership, and history. Leaving out public federation and end-to-end encryption keeps custom implementations small. Use TLS to protect the connection between clients and the server; it does not hide messages from the server.

Frames are JSON over a bidirectional transport, with WebSocket as the reference transport.

The protocol is incremental. The mandatory core is enough for a working chat: a `server` greeting, `auth`, identities, rooms as logs, and `message`. Everything else is an optional capability that a server advertises in its `server` frame, each with a fallback for clients and servers that lack it. Nothing is negotiated. Frames use the shape of JSON-RPC 2.0 requests, responses and notifications, without the `jsonrpc` key.

To implement Apron, read PROTOCOL.md, start with the core and its conformance checklist, then add capabilities as needed. Validate frames against the JSON Schema and test against the wire fixtures.

The full specification is also at https://apron.chat/llms-full.txt, in one file. Each part's Sections are the ids of its headings, such as #42-rooms in https://apron.chat/protocol#42-rooms, and each is in a comment above its heading in the Markdown, such as <!-- #42-rooms -->. Requesting https://apron.chat/protocol with `Accept: text/markdown` returns the specification as Markdown.

## Specification

- [PROTOCOL.md](https://apron.chat/protocol.md): The authoritative Apron Chat Protocol definition, current version. Also in four parts, for agents that can't read the whole file at once:
  - [Core](https://apron.chat/protocol-core.md): The introduction and required sections (§1–3), enough for a working implementation. Sections: #apron-chat-protocol #1-transport--framing #11-envelope-and-replies #12-retries-and-deduplication #2-identifiers #21-log_id #22-message_id #23-records-and-replay #24-opaque-ids #3-core #31-server-frame #32-authentication #321-bearer-tokens #322-order #33-identity #331-user-objects #332-profile #333-changes #334-roles #34-rooms #35-messages #351-creating #352-rendering #353-delivery #354-references #355-mentions #36-core-conformance-checklist
  - [Capabilities](https://apron.chat/protocol-capabilities.md): The optional capabilities (§4). Sections: #4-capabilities #41-command #42-rooms #421-listing #422-membership #423-updates #424-creating-and-editing #43-history #431-a-rooms-log #432-bounds-and-order #433-availability-and-retention #434-compaction #435-replay-and-recovery #44-edit #45-status #451-values #452-delivery #453-the-status-request #454-sign-in #46-activity #47-reactions #48-embeds-and-avatars #481-opengraph-metadata-og #482-embed-identity #483-writes #484-embedupload #485-embedstream #486-avatars #49-push #491-registration #492-kinds #493-payload #494-wake #410-webauthn-authentication #411-email-and-external-sign-in #4111-proposals #4112-temporary-tokens #4113-approval #4114-email #4115-external #412-ext
  - [Informative](https://apron.chat/protocol-informative.md): Security considerations, conventions and valid scenarios (§5, appendices A–B). Sections: #5-security-considerations #51-trust-model #52-authentication #53-identity-and-access-control #54-untrusted-content #55-network-privacy-and-server-requests #56-resource-limits #appendix-a--conventions-informative #a1-system-identities-and-scoped-notices #a2-field-naming #a3-prefixes-in-text #a4-links #appendix-b--valid-scenarios-informative #b1-the-server-sends-a-welcome-before-auth #b2-a-bot-connects-posts-once-and-disconnects #b3-an-invite-token-signs-up-several-people
  - [Draft](https://apron.chat/protocol-draft.md): Designs under consideration, not yet part of the protocol (appendix C). Sections: #appendix-c--under-consideration #c1-webrtc-signaling-for-audio-video-and-peer-to-peer-connections #c11-joining #c12-reclaiming-and-leaving #c13-signaling #c14-apron-over-a-data-channel #c2-multiplexing-envelope #c3-actions-embed #license
- [HISTORY.md](https://raw.githubusercontent.com/shazow/apron/main/HISTORY.md): Changes by protocol version
- [JSON Schema](https://raw.githubusercontent.com/shazow/apron/main/schema/apron.schema.json): An informative JSON Schema of every frame, for validation and editor completion
- [Wire fixtures](https://raw.githubusercontent.com/shazow/apron/main/tests/fixtures/wire/README.md): Portable JSON scenarios that implementations can test against

## Servers

- [apron-server-go](https://github.com/apron-chat/apron-server-go): The Go reference server for self-hosting, implementing every capability
- [apron-server-cloudflare](https://github.com/apron-chat/apron-server-cloudflare): The public demo server at wss://server.apron.chat/, a Cloudflare Worker with a SQLite Durable Object
- [python-minimal](https://raw.githubusercontent.com/shazow/apron/main/servers/python-minimal/apron_server.py): A single-file core server in Python with capability `history`, a starting point to read or adapt
- [js-minimal](https://raw.githubusercontent.com/shazow/apron/main/servers/js-minimal/apron-server.js): The same in JavaScript for Bun, with no dependencies

## Clients

- [apron-web](https://github.com/apron-chat/apron-web): The SvelteKit web client deployed at https://web.apron.chat
- [apron-pr-bot](https://github.com/apron-chat/apron-pr-bot): A bot that posts GitHub pull request activity to the demo server

## Optional

- [README](https://raw.githubusercontent.com/shazow/apron/main/README.md): Goals, assumptions, trade-offs and background
- [FAQ](https://raw.githubusercontent.com/shazow/apron/main/FAQ.md): Why the server is trusted, how Apron compares to XMPP, Matrix, Slack and Discord, how AI was used to build it, and the name
- [Live demo](https://web.apron.chat/): The web client, connected to wss://server.apron.chat/