An open protocol · version 0.1

Let an AI agent drive your web app. You hold the reins.

Reins is a protocol, and a reference implementation, for letting an AI agent drive a web app that is running in a browser tab. The agent reads the screen as a compact tree, calls the app's own actions, moves a visible cursor and puts data in front of the person. The app decides what an agent may do, the person watches and can stop it, and a kiosk can lock it down to a fixed allowlist.

Try it in this tab Read the wiki GitHub

Protocol 0.1, package 0.1.0, Apache-2.0. A first version: the wire format may change before 1.0.

An agent on a rein The cursor of an AI agent runs two app actions, cart.add and customer.set. A rein held by the person stops it short of the third, order.submit, which waits for the person. cart.add customer.set order.submitwaits for you you AI agent
A safe action runs. A sensitive one waits for you.

See it run

One real session, thirty seconds

One real session of the Brew Kiosk demo in the repository, recorded in Chromium. The agent works through the hub, and Allow, Pause, Resume and Stop are real clicks. The film and the stills were recorded before the panel existed: today the indicator's text opens it, and the card for an action has a third button, “Always allow”. The playground runs the current driver.

What happens in the film, which has no sound: the page asks before the agent Barista AI may attach, and the person allows it. The agent adds a latte and two mochas and types a name. The person presses Pause, and the agent's next two commands come back refused. Placing the order waits for the person, who allows it, and the order is placed. The person presses Stop, and the agent's access is gone. How the film was made.
  • The Brew Kiosk page dimmed behind a card: Barista AI wants to control this page. The card lists the scopes it asks for, and has Deny and Allow.
    The page asks before an agent may attach.
  • The kiosk menu with the agent's labelled cursor over the Latte card, a highlight around it and a toast from the agent at the top.
    The agent's cursor, a captioned toast, a highlight.
  • The order filled in with a latte and two mochas, a name typed, a bar chart in the Insights panel, and the agent's cursor at the total.
    Order filled in, chart sent from a file, the live pointer stream circling the total.
  • A card: Barista AI wants to run an action, order.submit, marked sensitive, with Deny and Allow.
    A sensitive action waits for the person.
  • A modal dialog opened by the app. The indicator, with Pause and Stop, stays in the corner above it.
    The indicator stays reachable when the app opens a modal dialog.

How it works

One protocol, two shapes

An agent talks to a hub, and the hub talks to the driver in the browser tab, both over reins.v1. A safe action passes the policy and runs. A sensitive action waits until the person approves it on screen.

An agent talks to a loopback hub, and the hub talks to the driver in the browser tab, both over reins.v1. A safe action passes the policy and runs. A sensitive action waits until the person approves it on screen.
  • agent
  • hub on loopback
  • driver in the tab

With a hub

The agent is outside the browser and reaches the tab through a broker on loopback. The hub authenticates both sides, issues grants, enforces its own policy and rate limits, and keeps the audit log. This is the shape for an agent harness: the agent SDK, the shell tools, or the MCP adapter.

Run the demo with a hub

  • assistant
  • broker
  • driver
  • your app

In the tab

The assistant runs in the page itself: no process and no network, the same protocol over in-memory links. The same grants, policy and consent prompts apply. The playground on this site is exactly this shape.

Open the playground · How the in-tab shape works

What it gives you

Live, cheap in tokens, guarded, kiosk ready

  • 1message
    per cursor move

    Live

    One message moves the cursor smoothly at display rate. A binary pointer stream with credit-based flow control carries live trajectories.

  • ≈1,000characters
    to learn an app

    Cheap in tokens

    A model learns an app from a prompt card of about a thousand characters, reads the screen as a tree of similar size, and afterwards gets deltas of a few hundred. Bulk data goes to the screen without passing through the model.

  • 3answers: allow,
    confirm, deny

    Guarded

    Actions carry a risk tier. Sensitive actions need the person's approval on screen, private fields are never read, and nothing in the protocol evaluates agent-supplied code. Authenticated sessions are sealed frame by frame.

  • 0synthetic input,
    no navigation

    Kiosk ready

    A profile for unattended stations: allowlisted actions, annotated elements only, no synthetic input, no navigation, hash-chained audit log.

In the person's hands

The indicator is a button, and only you can press it

While an agent is attached, a pill in the corner of the page says so, with Pause and Stop. Its text opens a panel. No agent and no message can open it, close it or press anything in it. Script that runs in the page itself is outside that promise: keep it out with a strict Content Security Policy.

How much it asks is yours to set

For each attached agent you choose a level, from asking every time to never. A grant starts at ask, unless you set that agent to Strict before.

level what an act request does
strict asks every time, also for an action the policy allows
ask asks when the policy says confirm or the hub sent c:1
auto runs without asking, unless the action's risk is dangerous
bypass runs without asking

You can also say Allow, Ask or Block for a single action, switch single scopes of the grant off, and see what the agent did. Whatever lets an agent do more takes a second step that names what stops asking, and the pill then shows the level. A deny of the app or the hub stays a deny at every level. What loosens ends with the grant; what you tightened stays with that agent for as long as the page is open.

Permission levels

Talk to the agent that is driving

The same panel has a Chat tab. You type to the agent that is driving the page, and it answers there while it works. What you type is a request, never an approval: an action that needs your approval still asks on its own prompt, and while that prompt waits the chat is hidden. Agents hear each other only once you say so.

The chat is drawn in the app's page, so the app can read it, as it can any of its own fields.

Chat · Serving it, and what that hands out

Beyond the tab: Electron, and a second agent

An Electron window is a page too. An app you write gets its link from its own main process, with no socket on the page side. An app you did not write can be adopted through its debugging connection, which gives an attached agent the whole window: read what that means first.

Two walk-throughs put two agents to work, Claude Code driving Hermes Desktop and both on one page, with every step marked as run or not run. Nothing was run with a model.

Build it in · Adopt an app · Claude and Hermes

Install and first run

From an install to an agent on the page

Reins ships as one package, @offensiveadhd/reins. It needs Node 22 or newer to build and to run the hub; the browser parts need no Node at all.

  1. Install the package

    From Git, in a project that has a bundler: the package builds itself on install. It is not on the npm registry. A static page with no build step copies one file, dist/bundle/reins.js (446 KiB, unminified), and imports it.

    Shell
    npm i github:offensiveadhd/reins

    Every way to install it

  2. Make your app drivable

    Declare the app's actions with a risk tier, the views it can show and the state an agent may read. The driver does the rest: the UI tree, the cursor, the consent prompt and the indicator.

    JavaScript
    import { createDriver } from '@offensiveadhd/reins';
    
    const driver = createDriver({
      app: { id: 'brew-kiosk', name: 'Brew Kiosk', version: '1.0.0' },
      hub: 'ws://127.0.0.1:7346',
      policy: 'guarded', // or 'open', 'kiosk', or a profile with overrides
    });
    
    driver
      .action(
        {
          name: 'cart.add',
          description: 'Add a drink to the order.',
          risk: 'safe',
          params: {
            type: 'object',
            properties: { sku: { type: 'string', enum: ['latte', 'mocha'] }, qty: { type: 'integer', minimum: 1, maximum: 9 } },
            required: ['sku'],
          },
        },
        ({ sku, qty = 1 }) => cart.add(sku, qty),
      )
      .action({ name: 'order.submit', description: 'Place the order.', risk: 'sensitive' }, () => cart.submit())
      .view({ name: 'chart', description: 'Bar chart panel.' }, (data) => renderChart(data))
      .state('cart', () => cart.summary());
    
    await driver.connect();

    Make an app drivable · Writing good actions

  3. Start a hub and drive the page

    Start a hub in the project that installed the package, then connect from Node. The hub writes its token to a file and prints the path; the SDK finds it.

    Shell
    npx --no -- reins-hub --profile guarded --allow-origin http://localhost:5173
    JavaScript
    import { connect } from '@offensiveadhd/reins/agent';
    
    const client = await connect({ name: 'Barista AI' });
    const [surface] = await client.surfaces();
    const kiosk = await client.attach(surface.s, { scopes: ['observe', 'act', 'cursor', 'show'] });
    
    console.log(kiosk.card());              // the prompt card for a model
    console.log(await kiosk.observeText()); // the screen, compact
    await kiosk.cursor.move('#menu.latte');
    await kiosk.act('cart.add', { sku: 'latte', qty: 2 });
    console.log(await kiosk.observeText()); // only what changed

    Drive it from Node · From a shell, with nothing registered

  4. Or hand it to an MCP harness

    The adapter is a stdio MCP server with eight tools. With Claude Code, once a hub has run on the machine, register the launcher, then start a new agent session.

    Shell
    claude mcp add --scope user reins node "$HOME/.reins/reins.mjs" mcp

    Use it from Claude Code and other MCP harnesses

Policy

Three profiles, from a laptop to a kiosk

The app picks a profile, or a profile with overrides. The hub has a policy of its own, and a request has to pass both.

open guarded kiosk
intended for local development a person's own browser unattended stations
attach allowed the person approves allowed for a provisioned agent
safe / sensitive / dangerous actions allow / confirm / confirm allow / confirm / deny allow / deny / deny
scopes all all observe, act, cursor, show
what the tree exposes interactive elements interactive elements annotated elements only
navigation same origin same origin off
a page inside a frame refused, unless framed refused, unless framed refused, unless framed
person's controls pause, stop pause, stop pause
levels the person may set strict, ask, auto, bypass strict, ask, auto, bypass strict, ask
panel on the indicator yes yes no
chat with the person yes; agents hear each other yes; agents hear each other once the person switches it on no

What every row means · Deploying a kiosk

Open, and built to be checked

A protocol you can implement and verify

0.1protocol

Specified

The wire types are one file and the behaviour behind them is one document, in which the words MUST, SHOULD and MAY are normative. The same frames run over a loopback WebSocket and over an in-page message port.

Read the specification

205requirements

Traceable

Each conformance test names the requirement and the section it checks, and a meta-test fails when a normative sentence in the spec has no test. 14 files of language-neutral test vectors, computed independently of this implementation, are there for anyone writing another one.

Requirements index · Test vectors

75threats, each with what stops it

Attacked, and honest about it

Reviewers that did not write the code attacked it while it ran. The security model records what each review found, what was changed and what is left as a stated limit, and says that the fixes after the latest reviews have not been reviewed again. It also lists what Reins does not protect against. Read that list before deploying.

What Reins does not protect against · Review history

Browsers, Electron, models

What has been tested, and what has not

  • tested

    The demo has been run end to end in Chromium, with the page served from loopback.

  • not tested

    Firefox, Safari and pages served from a public https: origin have not been tested. See the browser notes in the security model.

  • no network

    The in-tab shape needs no network access and so is not affected by loopback restrictions.

  • tested

    Electron on Windows, with a real Electron and a person played by real mouse and keyboard input. What was tested names each scenario.

  • not tested

    Electron on macOS and Linux, and a packaged app. Nothing was run with a model, inside a real Claude Code session, or against a live Hermes Desktop.