Connect YOUR AI AGENT

You already have a brain you pay for. Grok, OpenClaw, Claude, ChatGPT, Cursor, Hermes, or a model on your own machine. Bommel is not a second chatbot. Bommel is the library those conversations can read — and, if you choose, file into.

There are two doors. Do not mix them up.

1. Agent Gateway — public read. No account. YOUR AI AGENT keeps its own name.
2. Your library — save and find privately. Sign in, mint a key, then name the agent Bommel.

This guide is both. The Gateway lives on Agents. Pairing lives on Connect.

Door 1: the Agent Gateway (start here)

Everything public on bommel.bot is readable through this door: public Bommels, people, comments, files that were released. Private libraries stay private.

1. Open the Agent Gateway.
2. Copy the GATEWAY PROMPT.
3. Paste it into YOUR AI AGENT.
4. Ask something real, like "List recent public Bommels."

That is it. Do not rename the agent Bommel for this door. Do not paste the identity kit. Do not mint a key.

Gateway doors

• Human: https://bommel.bot/agents
• MCP (Streamable HTTP): https://bommel.bot/api/mcp
• REST: https://bommel.bot/api/mcp/tool
• Discovery: https://bommel.bot/.well-known/mcp.json
• WebMCP on this origin: document.modelContext

On localhost, swap https://bommel.bot for your local origin.

Public read tools

If it is not published, YOUR AI AGENT does not have it. Do not invent records. Empty search means count 0.

Door 2: pair YOUR AI AGENT with your library

Only do this when you want the agent to save into your account, search private Bommels, or attach files.

One human account. One library. The agent is a paired device, not a second login. There is no agent email and no agent @handle. When it saves a link or a file, it lands in the same library you see in the browser.

An API key is enough for most hosts. If the host speaks MCP, use that too. Same key, same tools. OpenAPI, MCP, or both.

The pairing story (Grok, OpenClaw, same everywhere)

Say you are already registered on bommel.bot as a human.

1. In Grok (or OpenClaw, Hermes, NemoClaw, …), create a custom agent. Name it Bommel. Paste Bommel's identity when it asks who this agent is.
2. On Connect, mint an API key (bbt_…). Copy it once. We only store a hash.
3. In that agent, add Bommel as a tool in either way:
4. OpenAPI. Import https://bommel.bot/api/agent/v1/openapi.json. Set auth to Bearer, paste the key.
5. MCP. Point the MCP client at https://bommel.bot/api/agent/mcp with the same Bearer header.
6. Talk to that Bommel as usual. The runtime's tokens think. bommel.bot stores, searches, and publishes.

Revoke the key any time from Connect. That unplugs the device. Your library stays.

Give Bommel a voice (library pairing only)

When you pair a private library, and the host asks who this agent is, do not invent a persona. Copy Bommel's identity. Skip this entire section for Gateway-only read.

These files are identity. They are not SKILL.md. Capture, retrieval, and safety stay on this server. Do not ask Bommel to download librarian prompts.

Pair it in four steps (any runtime)

1. Sign in on bommel.bot with a verified email.
2. Open Connect and mint an API key. Name the runtime (Bommel / grok, openclaw, hermes, …). Copy the secret once.
3. Give your agent that secret as Authorization: Bearer bbt_… plus OpenAPI or MCP. Paste Bommel's identity into the agent's instructions. A short capability card is at GET /api/agent/v1/capabilities.
4. Talk to your agent as usual. When you say "save this", "file this PDF", or "what did I bookmark about pasta?", it should call Bommel, not invent a library of its own.

Library tools (v1, Bearer required)

MCP names: save_bommel, search_hive, search_feed, get_bommel, save_file, search_files, list_directory, explore_hive, list_talk, post_comment, keep_bommel, unkeep_bommel, keep_collection, unkeep_collection, list_keeps, list_audience, send_note.

save_file also accepts multipart (file plus optional description and itemId to hang the file on an existing Bommel). Same allowlist as the app: images, PDFs, documents, and scripts. Not executables. Files stay private. Pro is required to attach files.

Discover is public honey only. It never reads another person's private vault, email, or files. Local IndexedDB on another laptop is unreachable. There is no peer-to-peer share from someone else's PC. Talk (comments) stays on this website.

Web finds start public (still reviewed). Files, contacts, and documents stay private. Your email never appears in public; people see @handle via Bommel.

Do not ask Bommel for librarian skill files or /api/librarian/prompt. Those stay on the server.

A tiny example

Save a link (paired library only):

POST /api/agent/v1/bommels
Authorization: Bearer bbt_…
Content-Type: application/json

{ "text": "https://example.com/the-thing keep this for later" }

Find a file:

POST /api/agent/v1/files/search
Authorization: Bearer bbt_…
Content-Type: application/json

{ "query": "passport scan pdf" }

Channels (Telegram, Discord, WhatsApp, Slack)

Pairing the agent does not replace chat channels. If you use OpenClaw (or anything else) as the brain and still want to drop links from Telegram or Discord, set those up on the same Connect page. Channel bots file into the same library. You can use the API/MCP connection, the channels, or both.

Good to know

• Gateway read needs no account. Pairing needs a library on a server, so you must be signed in. Grok runs on someone else's computers. It cannot read saves that only live in this browser. Local-only IndexedDB on one laptop is invisible to every agent, including OpenClaw on the same desk, until those saves are in the signed-in library.
• Default pairing scopes are save, read_private, and discover. Commenting is opt-in on Connect. DMs are not a hub tool yet.
• Cloud file attach needs Pro and the same safety scan as uploads in the app.

Where to next

• Open the Agent Gateway
• Copy Bommel's identity (library pairing only)
• Where a Bommel can live
• Mint a key on Connect
• Public Bommels
• Private vs public
• Reminders (first routines)