Start · about 5 minutes

The desk

The desk is one line of middleware. It notes what AI agents ask your site to do, learns the requests your site answers with success, and offers them to agents as actions once you approve. You do not describe your site or write an API for it.

1 · Install

terminalbash
npm install @bubblio/door
.envbash
BUBBLIO_API_KEY=bbl_…   # dashboard → API keys
middleware.tsts
import { withBubblioDesk } from '@bubblio/door/desk'

// The whole integration. The desk answers its own paths under /.well-known/bubblio
// and lets everything else through to your site untouched.
export const middleware = withBubblioDesk()

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
}

Deploy and load any page. The dashboard's Home shows “Installed” with your site's address. If you already have middleware, wrap it:

middleware.tsts
import { withBubblioDesk } from '@bubblio/door/desk'
import { myMiddleware } from './lib/my-middleware'

// Already have middleware? Wrap it. Yours still runs once for every request.
export const middleware = withBubblioDesk(myMiddleware)

The desk works in Next.js middleware today. Your site behaves exactly as before for people in browsers.

2 · What the desk learns

The desk records visits from AI assistants and scripts. People in ordinary browsers, search crawlers and uptime monitors are not recorded. From those visits it builds actions with plain code, not with an AI model:

  • Only a request your site answered with success (a 2xx status) can become an action.
  • An action is proposed after 3 successes from at least 2 separate senders.
  • A value is fixed into an action only when 3 or more separate senders all sent the same one. Otherwise the agent fills it in.
  • A request that carried a password, card or one-time code teaches the desk nothing. A login or card form never becomes an action, because every request it accepts carries one.
  • Routes that delete, cancel, refund, or touch passwords, email or money are flagged.

An AI model writes a title and one plain sentence for each action, and the desk adds what the action returns from your site's own answers. You write and maintain none of it. The model cannot change what an action does, and the real request is always shown next to its words. Bubblio covers this for up to 100 actions a month per account; with your own Anthropic key in Settings there is no limit.

3 · You approve

Open Actions in the dashboard. Every proposal shows the exact request it sends, which values are fixed, and which the agent fills in. Allow it, or block it. Once you decide, later traffic cannot reshape that action: the request, its inputs and whether it is live stay as you approved them. The one line saying what it returns follows your own site's answers.

ModeWhat the desk does by itself
WatchRecords visits. Learns nothing, offers nothing.
Ask me (default)Learns and proposes. Nothing goes live until you allow it.
AutopilotA read-only action goes live alone if it has no flags and your own pages link to it. Anything that changes data still waits for you.

Only you, signed in to the dashboard, can change the mode or allow an action. An API key cannot.

4 · Agents find and use the actions

Allowed actions appear at your agent door next to any actions you wrote by hand. The door must be switched on in the dashboard.

You add nothing to your site so that agents can find it. Once the door is on, the middleware tells them itself:

  • A page served to an AI assistant or a script carries one extra line: this site has a desk for agents, and the guide is at /.well-known/bubblio.
  • The guide is a short text page: one address and three calls.
  • The desk also answers /llms.txt, /mcp and /.well-known/mcp, each only when your site has none of its own.

People in browsers, search and training crawlers, and headless browsers never get any of it. So a person can tell their agent “go to yoursite.com and add two pens to my cart”, with no address to copy and no setup command.

terminalbash
# What an agent does when a person says "go to yoursite.com and …":
curl -s https://yoursite.com/.well-known/bubblio     # the guide: one address, three calls

#   list_actions   → the actions you allowed
#   quote          → a lookup answers right away. A change is prepared,
#                    or returns a connect link if it needs a user
#   confirm        → runs a prepared change once, and returns your site's answer

# The same address is an MCP server, for agents that prefer to add one:
claude mcp add shop --transport http https://api.bubblio.dev/agent/{doorId}/mcp

In a chat app that has the Bubblio connector, the person can say “use yoursite.com”: the connector asks your site which door is its own.

KindWho may run it
ReadsAny agent, in one call. Without a connection it sees what a signed-out visitor sees. A connected agent sees what its user sees.
Changes thingsAn agent a user has connected. It acts as that user.
MoneyA connected agent, and the user approves each time with a passkey only they hold.

Daily limits, for each site:

  • Reads by agents with no connection: 1,000 a day, shared. One address can use at most a quarter of them.
  • Reads by a connected agent: 200 a day for each connection, outside that shared 1,000. Traffic from strangers cannot use them up.
  • Actions that change something: 50 a day, and 20 a day for each connection.

An action's answer passes through Bubblio on its way to the agent. Bubblio does not keep what a read answered. For an action that changes something it keeps the answer with the receipt, so a repeated call gets the same result and never a second run.

Acting for a signed-in user

You write no code for this. When an agent needs to act for someone:

  1. The agent receives a one-time link and passes it to its user.
  2. The user opens it on your own site. If they are not signed in, the page says so and opens your sign-in page. It carries on by itself when they come back.
  3. The page lists, in plain words, what the agent will be able to do. The user presses Connect.
  4. The desk gives the agent its own separate session and signs that browser out, so the two never share one login.

The desk does not take a cookie as proof that someone is signed in. It opens a few of your own read-only pages on your server, once with the visitor's cookies and once with none, and compares your site's two answers. Your site decides. The cookies never leave your server, and when your site gives no clear answer the desk does not block the person.

The desk finds your sign-in page from the link on your home page. Two settings exist for the cases where that is not what you want:

middleware.tsts
// Only if the desk picks the wrong sign-in page, you do not want agents told,
// or you do not want the field names of your answers noted:
export const middleware = withBubblioDesk(undefined, {
  signInPath: '/login',
  announce: false,
  recordAnswers: false,
})

The session is stored encrypted. Opening it needs two secrets: your site's API key, which Bubblio stores only as a hash, and the agent's own key. The agent never sees the session; it is used only to replay actions you allowed.

A login the server can refresh from cookies works with no code. A login that lives in browser storage, or that only a browser can refresh, needs the hand-written path in Consent & phone connect.

What leaves your site

The desk removes things inside your site, before anything is sent:

  • Sent: the method, the path with ids replaced, the status, and the names and types of the fields an agent sent.
  • Sent since 1.3.0: the names and types of the fields in your site's JSON answer (for example id, name, price), so the desk can tell agents what an action returns and which lookup gives the value for an input. Never a value from the answer. A name is sent only where the desk is sure the key is a field and not data: a short plain word, in a list item or in an object whose values are of different kinds. Keys that could be data (an object keyed by user, id or address), names that sound like a credential, and names the caller itself sent are left out. Agents are told a name only after two separate senders were each given it. Turn all of it off with recordAnswers: false.
  • Never sent: cookies, headers, the visitor's address, the values people typed, and anything your site answered with. Short option-like values an agent sent (for example sort=price) are kept so they can be fixed into an action.
  • Recording never blocks or changes your site's answer. If Bubblio is unreachable, your site carries on.

The desk counts separate senders by network address, and only believes an address header on the platform that writes it (Vercel, Fly, Netlify, Cloudflare Workers). If your site sits behind a proxy the desk cannot see, such as Cloudflare in front of your own server, add clientAddressHeader: 'cf-connecting-ip'. Without it everything still works; the desk is only slower to propose actions.

Prefer to write an action yourself?

You still can. Hand-written actions are the way to add prices, custom checks, or anything the desk cannot see from traffic. See the hand-written quickstart and Actions. If a hand-written action and a learned one share a name, yours wins.