The Reins wiki
Everything about the protocol, in one place
The Reins wiki: getting started, the concepts behind the protocol, guides, reference, notes for implementers and the community pages.
Start
From nothing to a page an agent can drive.
- What is ReinsA protocol, and a reference implementation, that lets an AI agent drive a web app running in a browser tab, under the control of the app and of the person using it.
- QuickstartRun Brew Kiosk, the demo app in the repository, with a hub and a scripted agent, and watch an agent order a coffee under your control.
- Make an app drivableInstall the package, create a driver, declare actions, views and state, and mark the elements an agent should see.
- Drive it from NodeStart a hub, connect with the agent SDK, attach to a page and drive it. Where the SDK finds its key, what the surface handle offers, and how refusals arrive.
- Claude Code and MCPRegister the Reins MCP adapter, a stdio server with a small set of tools, so a model in an agent harness can attach to a page, drive it and talk with the person there.
- Shell toolsAn agent harness that has a shell reaches a page with one command line, with no registration, no restart and no path. The same tools as the MCP adapter.
- The in-tab shapeRun the assistant in the page itself. The page hosts the broker and both sides talk over in-memory links, with no hub process and no network.
Concepts
How the protocol works, one idea at a time: from the handshake to permission levels and chat.
- Roles and trustThe three roles of the protocol, surface, agent and hub, and who is trusted with what.
- Transports and framingThe two transports, a loopback WebSocket and an in-page port, and the text and binary frames that both carry.
- Handshake and sealingHow a peer and the hub prove a shared secret to each other without sending it, and how every message after that carries a MAC bound to the handshake.
- Manifest and prompt cardHow a surface describes itself, and the short text rendered from that description that teaches a model to drive the app.
- Grants and scopesWhat an agent is allowed to do on one page, how it asks, who can narrow the answer, and how a grant ends.
- Policy profilesThe three profiles, open, guarded and kiosk, what each row of their table means, how single actions are overridden, and why a request has to pass two policies.
- ConsentThe prompt that asks the person before an agent attaches or runs a sensitive action, and the rules that keep an agent from getting a yes it did not earn.
- Human controlThe person can always see that an agent is attached, can pause it or stop it at any moment, and wins when both use the page at once.
- Permission levelsThe panel that opens from the indicator. For each attached agent the person sets how much it asks, a rule for single actions and which scopes are on, and sees what it did. Only the person can change any of it.
- ObservationHow an agent reads the screen, as a flat tree of the elements that matter, with stable handles, private fields that are never read, and deltas after the first reading.
- Cursor and the pointer streamOne message glides the agent's cursor at display rate. For live trajectories, a binary stream with credit-based flow control carries points.
- Rate limits and capacityThe token buckets, capacities and admission rates that keep one agent, or a flood from either side, from exhausting the hub or freezing the page.
- The audit logWhat the hub records about every connection, grant and request, how the records are chained so that edits show, and why the hub refuses to act when it cannot record.
- ChatThe chat room in the panel. The person at the page talks with the agents attached to it. Who hears whom, the switch that lets agents hear each other, what chat can never do, and what the page can see of it.
Guides
Deploying, annotating, serving the chat, Electron, and fixing things.
- Kiosk deploymentHow to run Reins on an unattended station. The kiosk profile, the surface key, the service account, the audit log, and the checklist from the security model.
- Surface keysA key that lets a page and the hub prove themselves to each other. What it buys, how to set it up, and when it protects nothing.
- Actions and risk tiersHow to declare actions an agent can use well, with schemas that reject bad arguments before your code runs, results worth returning, and a risk tier that puts the person in the loop where it matters.
- Chat from a Claude Code subagentA Claude Code subagent that serves the Chat tab of a page from inside the session that holds the grant. Rendered from integrations/claude-code/README.md.
- Serve chat from any command-line agentAnswering the chat with any program, and what that hands to whoever is at the page: read the warnings first. Rendered from integrations/chat-serve/README.md.
- Privacy annotationsFour attributes decide what an agent sees of your page. Name what it should use, hide what it should not see, and mark what it must never read.
- Running under a strict CSPThe Reins bundles run under a Content Security Policy with no inline script, no inline style and no eval. What to allow, and why a strict policy is part of the security model.
- TroubleshootingEvery error code of the protocol with what causes it and what to do, and the problems that show up before any code does.
- Electron: build it inAn Electron app you write is a surface with no socket on the page side. Three small pieces, one per place Electron runs your code, and what origin your page has.
- Adopt an Electron appreins-electron loads the driver into an Electron app you did not build, through its debugging connection. What an attached agent can then do, how to narrow it, and what a debugging connection means.
- Claude and HermesTwo walk-throughs with every step marked as run or not run. Claude Code drives Hermes Desktop, and Claude and Hermes work together on one page while you watch and can pause, stop or change either one.
- The Hermes Desktop pluginA Hermes Desktop plugin that makes the Hermes window a surface with three named actions. Built and statically checked, not run in Hermes. Rendered from integrations/hermes-desktop/README.md.
Reference
Methods, events, codes, fields, commands and the canonical documents.
- MethodsEvery request an agent can send, with its parameters, its result and the scope it needs, and how a surface behaves for each.
- EventsThe event topics, what each carries, who receives it and which need a subscription.
- Error codesThe complete list of error codes in protocol 0.1, what each means and where the specification uses it.
- Policy fieldsEvery field of a policy, what it controls, who enforces it, and its value in each of the three profiles.
- LimitsEvery size, time and count the protocol fixes, in one place. Frame sizes, timeouts, capacities, rates and the bounds on prompts and observations.
- CLIThe commands the package installs, with the help text each prints. The hub, the agent command, the MCP adapter, the shell tools and the command that adopts an Electron app.
- SDK APIThe public API of the reference implementation. The driver for pages, the agent SDK, the broker and the hub, the MCP adapter, and the core every part is built on.
- SpecificationReins Protocol 0.1 in full: the normative text, rendered from docs/SPEC.md.
- Security modelWho can attack an agent-driven page, what stops them, and what Reins does not protect against. Rendered from docs/SECURITY.md.
- The chat guideHow the chat behaves, how an agent uses it and how to serve it from a harness, in full. Rendered from docs/CHAT.md.
- The Electron guideReins in Electron in full: building it in, origins, adopting an app, the two walk-throughs with Claude and Hermes, and what was tested. Rendered from docs/ELECTRON.md.
Implementers
Writing another implementation and proving it conforms.
- Writing another implementationWhat it takes to implement Reins in another language or runtime. What the contract is, what has to match exactly, and how the vectors and the conformance suite tell you that you got it right.
- The conformance suiteWhat the conformance suite checks, how to run it and what it does not cover. Rendered from conformance/README.md.
- Test vectorsLanguage-neutral test vectors for the parts of the protocol that two implementations have to compute identically. Fixed inputs and expected outputs, browsable here and downloadable as JSON.
- Requirements indexEvery requirement the conformance suite checks, grouped by section of the specification, with the normative sentences it covers and the tests that check it. Generated from conformance/requirements.json.
Community
Contributing, proposing changes, reporting problems.
- ContributingHow to work on Reins. Building and testing the repository, what its checks expect of a change, and how to add or fix a page of this wiki with an ordinary pull request.
- Proposing a protocol changeWhat a change to the wire format or to normative behaviour has to touch, and how versioning lets implementations survive it.
- Reporting a vulnerabilityHow to tell the maintainers about a suspected vulnerability in Reins, what to include, and how to tell a vulnerability from a documented limit.
- FAQShort answers to the questions people ask first, each with a link to the page that has the long answer.
- GlossaryThe words Reins uses, each in a sentence or two, with a link to the page that explains it.
- ShowcaseApps, agents and implementations that use Reins. The list is empty so far, and this page says how to get on it.