askrobots / dbbasic-browser
Public
A desktop browser with x402 built in: when a page asks for payment, it pays in stablecoins and shows the content.
danq9
site icons (favicons) in tabs, address bar suggestions and the bookmarks panel
7249579
15 hours, 50 minutes ago
History
help.html · 45.9 KB · 253 lines
| 1 | <!doctype html> |
| 2 | <html lang="en"> |
| 3 | <head> |
| 4 | <meta charset="utf-8" /> |
| 5 | <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| 6 | <title>dbbasic-browser Help</title> |
| 7 | <style> |
| 8 | :root { color-scheme: dark; } |
| 9 | * { box-sizing: border-box; } |
| 10 | body { margin: 0; font: 15px/1.6 -apple-system, system-ui, sans-serif; background: #17171b; color: #d8d8de; display: flex; } |
| 11 | nav { position: sticky; top: 0; align-self: flex-start; height: 100vh; width: 220px; flex: none; padding: 24px 18px; border-right: 1px solid #2a2a30; background: #1b1b20; } |
| 12 | nav b { display: block; margin-bottom: 12px; color: #fff; font-size: 14px; } |
| 13 | nav a { display: block; padding: 5px 8px; border-radius: 6px; color: #9a9aa2; text-decoration: none; font-size: 13.5px; } |
| 14 | nav a:hover { background: #24242b; color: #fff; } |
| 15 | main { max-width: 820px; padding: 28px 40px 80px; } |
| 16 | h1 { font-size: 26px; margin: 0 0 4px; color: #fff; letter-spacing: -.01em; } |
| 17 | h2 { font-size: 19px; margin: 44px 0 8px; padding-top: 12px; color: #fff; border-top: 1px solid #2a2a30; } |
| 18 | h3 { font-size: 14px; margin: 22px 0 6px; color: #cde0ff; } |
| 19 | p, li { color: #c4c4cc; } |
| 20 | .lead { color: #8a8a90; margin: 0 0 8px; } |
| 21 | code, kbd { font-family: ui-monospace, Menlo, monospace; font-size: 12.5px; } |
| 22 | code { background: #23232a; padding: 1px 6px; border-radius: 4px; color: #e8e8ea; } |
| 23 | kbd { background: #23232a; border: 1px solid #3a3a42; border-bottom-width: 2px; padding: 1px 7px; border-radius: 5px; color: #e8e8ea; white-space: nowrap; } |
| 24 | pre { background: #101013; border: 1px solid #2a2a30; border-radius: 8px; padding: 12px 14px; overflow: auto; font: 12.5px/1.55 ui-monospace, Menlo, monospace; color: #d8d8de; } |
| 25 | table { border-collapse: collapse; width: 100%; margin: 8px 0; font-size: 13.5px; } |
| 26 | th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid #2a2a30; vertical-align: top; } |
| 27 | th { color: #8a8a90; font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: .04em; } |
| 28 | td:first-child { white-space: nowrap; } |
| 29 | .note { border-left: 3px solid #5b8cff; background: #1a2033; padding: 8px 14px; border-radius: 0 8px 8px 0; margin: 12px 0; } |
| 30 | .warn { border-left-color: #f0c674; background: #201a0a; } |
| 31 | a { color: #7aa2ff; } |
| 32 | </style> |
| 33 | </head> |
| 34 | <body> |
| 35 | <nav> |
| 36 | <b>Help</b> |
| 37 | <a href="#start">Getting started</a> |
| 38 | <a href="#shortcuts">Keyboard shortcuts</a> |
| 39 | <a href="#tabs">Tabs</a> |
| 40 | <a href="#reader">AI Reader</a> |
| 41 | <a href="#downloads">Downloads</a> |
| 42 | <a href="#loading">Loading indicators</a> |
| 43 | <a href="#x402">x402 payments</a> |
| 44 | <a href="#passwords">Password manager</a> |
| 45 | <a href="#automation">Automation API</a> |
| 46 | <a href="#identity">How we identify ourselves</a> |
| 47 | <a href="#security">Security model</a> |
| 48 | </nav> |
| 49 | <main> |
| 50 | <h1>dbbasic-browser</h1> |
| 51 | <p class="lead">A browser that pays for the web itself — with a built-in password manager and a remote-control API.</p> |
| 52 | |
| 53 | <h2 id="start">Getting started</h2> |
| 54 | <p>Type a URL and press <kbd>Enter</kbd>. Plain hosts default to <code>https://</code>; <code>localhost</code> and private-network addresses default to <code>http://</code>. Anything that isn't an address is a <b>search</b>, answered by askrobots.com. The first tab and every new tab open <b>askrobots.com</b> (<code>HOMEPAGE=https://…</code> changes that). The local x402 demo gallery is under <b>Help ▸ x402 Demo Gallery</b> (start it with <code>node apps/browser/demo/x402-demo-server.mjs</code>); <b>▶ Tour</b> always walks that gallery.</p> |
| 55 | <p>Toolbar, left to right: back / forward / reload, the address bar, then <b>Keep</b>, <b>Save</b> (to your askrobots bookmarks), <b>x402 tests</b> and <b>Tour</b> (the demo gallery), <b>Bookmarks</b>, <b>Chat</b>, <b>Reader</b> and <b>Passwords</b>. In a narrow window the buttons show only their icons.</p> |
| 56 | <p>The status bar along the bottom: on the left, what the page is doing (or where a link you point at goes); on the right, what the browser is using and spending: <b>Memory</b> (click for what each tab uses), <b>x402</b> (the payment inspector), your wallet balance, <b>Fund</b>, and <b>Paid</b> this session. A chip appears there when the automation API is on, and a red badge while the caller network is on.</p> |
| 57 | <p>Every feature is also in the menu bar: <b>File</b> (tabs, downloads), <b>View</b> (Reader, Chat, the x402 inspector, what the browser is using), <b>Go</b> (back ⌘[ or ⌘←, forward ⌘] or ⌘→, next and previous tab; the arrows go to a text field when one has the focus), <b>Bookmarks</b> (save ⌘D, show ⌘⇧B, Keep, kept copies), <b>History</b> (show ⌘Y, pause, forget) and <b>Tools</b> (passwords, connections, the wallet, the test gallery and tour).</p> |
| 58 | |
| 59 | <h2 id="shortcuts">Keyboard shortcuts</h2> |
| 60 | <table> |
| 61 | <tr><th>Action</th><th>Shortcut</th></tr> |
| 62 | <tr><td>New tab</td><td><kbd>⌘T</kbd> or <kbd>⌘N</kbd> (one window for now)</td></tr> |
| 63 | <tr><td>Close tab</td><td><kbd>⌘W</kbd> (middle-click a tab also works)</td></tr> |
| 64 | <tr><td>Focus the address bar</td><td><kbd>⌘L</kbd></td></tr> |
| 65 | <tr><td>Next / previous tab</td><td><kbd>⌘⇧]</kbd> / <kbd>⌘⇧[</kbd>, <kbd>Ctrl</kbd>+<kbd>Tab</kbd> / <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>, or <kbd>⌘⌥→</kbd> / <kbd>⌘⌥←</kbd></td></tr> |
| 66 | <tr><td>Go to tab 1–8, or the last tab</td><td><kbd>⌘1</kbd>–<kbd>⌘8</kbd>, <kbd>⌘9</kbd></td></tr> |
| 67 | <tr><td>Assistant</td><td><kbd>⌘J</kbd></td></tr> |
| 68 | <tr><td>Find in the page</td><td><kbd>⌘F</kbd> (Edit ▸ Find), then <kbd>Enter</kbd> / <kbd>⇧Enter</kbd> or <kbd>⌘G</kbd> / <kbd>⌘⇧G</kbd> for the next and previous match, <kbd>Esc</kbd> to close (the match stays selected, so <kbd>⌘C</kbd> copies it). Each tab keeps its own search. A site with its own find (an editor, a document) gets <kbd>⌘F</kbd> first; Edit ▸ Find always opens the browser's.</td></tr> |
| 69 | <tr><td>Reload the page</td><td><kbd>⌘R</kbd>, or ⟳ in the toolbar (✕ stops a page that is loading)</td></tr> |
| 70 | <tr><td>Open a link in a new tab</td><td>Right-click it › <b>Open Link in New Tab</b>, or <kbd>⌘</kbd>-click it (Ctrl+click on Windows and Linux), or middle-click it. The tab opens behind the page you are on</td></tr> |
| 71 | <tr><td>The right-click menu</td><td>On a link: open in a new tab, copy its address. On an image: open, copy, copy its address, save. On selected text: copy, search askrobots for it, ask the assistant about it (the text goes into the chat box for you to finish; nothing is sent on its own). In a text field: spelling suggestions, undo, redo, cut, copy, paste, select all. Anywhere else: back, forward, reload. And Inspect Element</td></tr> |
| 72 | <tr><td>Save the page as a bookmark</td><td><b>Save</b> next to the address (one click); <b>Bookmarks</b> lists them</td></tr> |
| 73 | <tr><td>Keep a copy of the page and close the tab</td><td><b>Keep</b> next to the address; <b>Bookmarks</b> › Kept copies lists and searches them</td></tr> |
| 74 | <tr><td>Open the page in your default browser</td><td><kbd>⌘⇧O</kbd> (File menu)</td></tr> |
| 75 | <tr><td>Close the password panel</td><td><kbd>Esc</kbd></td></tr> |
| 76 | <tr><td>Help</td><td><kbd>F1</kbd></td></tr> |
| 77 | </table> |
| 78 | <p>On Windows/Linux use <kbd>Ctrl</kbd> where this says <kbd>⌘</kbd>.</p> |
| 79 | |
| 80 | <h2 id="address">The address bar</h2> |
| 81 | <p>Type an address to open it, or anything else to search askrobots.com. As you type, a list shows what Enter will do first, then open tabs (pick one to switch to it), your askrobots bookmarks, pages from your history (from all your computers), your kept copies, search suggestions, and last, <b>Ask the assistant</b>. ↑ ↓ pick, Enter opens, Esc closes the list (twice puts the page's address back). A site you have saved, kept, visited or have open is completed as you type ("slash" → <code>slashdot.org</code>); type on to replace the completion, or delete it.</p> |
| 82 | <p>Tabs, bookmarks, history and kept copies are matched on this computer. For history the browser keeps a copy of the list (addresses, titles and times, never the pages' text) in a file only you can read; it is brought up to date from your askrobots account, so a page forgotten anywhere goes from the suggestions, and signing out deletes it. Search suggestions come from askrobots.com, and are asked for only when what you typed is not an address (never a path, a port or anything with <code>@</code>), without cookies, and never while the caller network is on; switch them off at the bottom of the list.</p> |
| 83 | <p>Tabs, suggestions and the bookmarks panel show each site's icon. The browser fetches a site's icon once, from the first of its pages you open (without cookies, and again after a week), and keeps it in a file only you can read. Typing never fetches one, so a page from your history that this computer has not opened shows the plain symbol. No icons are fetched while the caller network is on or for a site on your never-record list, and forgetting a site forgets its icon.</p> |
| 84 | <p><b>/ commands.</b> With askrobots connected, type <code>/</code> to list the askrobots tools your sign-in may use (the server decides which), with the site's short names too (<code>/note</code>, <code>/task</code>, <code>/search</code>, <code>/websearch</code>). Tab completes a name; the rest of the line is the tool's first argument (<code>/note buy milk</code>), and the row shows what will be sent before Enter runs it. Every command and its answer go into the chat, so you can ask about them next (“open the second one”); the assistant is told the answer came from your account, not from you. A save shows a note saying what was saved (“Saved note: buy milk (private)”) with <b>Open</b> for its page on askrobots; a search or list opens the chat, each thing found linked to its askrobots page. Links only ever point at askrobots itself. Once an answer from your account is in the conversation, anything the assistant does that could carry it out of the browser (typing into a page, opening an address) asks first, in any mode; Clear forgets it. A tool the server marks as destructive, or one it says nothing about, asks first: press Enter a second time. A tool that needs more than one argument says so instead of running. Without a sign-in, <code>/</code> only offers to connect and sends nothing; a line starting with <code>/</code> is never sent as a search. ⌘K is left to the page (askrobots' own search box uses it), even when the address bar has the focus.</p> |
| 85 | |
| 86 | <h2 id="tabs">Tabs</h2> |
| 87 | <p>Each tab is its own page with its own payment inspector, so spend is attributed to the page that caused it. A <b>⚡</b> on a tab means something was paid for there. Links that open a new window (<code>target="_blank"</code>) open as tabs; clicking a transaction in the inspector opens it beside the paid page rather than replacing it. Tabs are not yet restored between launches.</p> |
| 88 | |
| 89 | <h2 id="history">History</h2> |
| 90 | <p>While you are signed in to askrobots, the pages you visit are kept in your history on your askrobots.com account, so you can find one later by a few words you remember. Each visit keeps the address, the title, when, how long, and the page's visible text (up to 50 KB). Signed out, nothing is recorded.</p> |
| 91 | <ul> |
| 92 | <li><b>Never recorded:</b> sign-in and payment pages (by address, by title, or when a password field shows), pages on this machine or your private network, anything you looked at for under two seconds, sites on your never-record list, and anything while history is paused or the caller network is on.</li> |
| 93 | <li><b>Addresses are cleaned first:</b> the part after <code>#</code> and every query parameter are dropped, except the few that say which page it is (a YouTube video's <code>v</code> and <code>list</code>, a Hacker News <code>id</code>). askrobots drops them too.</li> |
| 94 | <li><b>Your controls:</b> the <b>History</b> button in the status bar pauses and resumes. The History menu forgets this page, this site or the last hour, and stops a site from ever being recorded. <b>Show History</b> (⌘Y) opens your history on askrobots.com, where you can search it and forget everything.</li> |
| 95 | <li><b>The assistant</b> can search your history to answer "where did I see…?", but it asks you every time, because what it finds goes to its AI company. It can never record or forget anything.</li> |
| 96 | <li><b>Never sent to the search site.</b> History lives on your account only. Pages waiting to be sent are held in memory; signing out, or in as someone else, throws them away.</li> |
| 97 | </ul> |
| 98 | <p>It needs the <code>history</code> permission on your askrobots sign-in. If the status bar says <b>History off</b>, connect to askrobots again from the assistant panel. The automation API has <code>history.state</code>, <code>history.flush</code>, <code>history.pause</code>, <code>history.forget</code> and <code>history.never</code>.</p> |
| 99 | |
| 100 | <h2 id="reader">AI Reader</h2> |
| 101 | <p>Click <b>Reader</b> (or <kbd>⌘⇧R</kbd>) for a clean reading view of the current page with a <b>TL;DR</b> at the top. The article is extracted on your computer with Mozilla's Readability and shown in a plain, script-free page; pages that aren't articles fall back to their visible text. Only the TL;DR comes from an AI provider, so a summary can never rewrite what you read — the original text is right below it.</p> |
| 102 | <h3>Privacy</h3> |
| 103 | <ul> |
| 104 | <li>Nothing is sent unless you click Reader. The first summary per provider each session asks first, naming the provider, model, site and amount of text.</li> |
| 105 | <li>Pages with a visible password field are never read.</li> |
| 106 | <li>Every provider call raises a toast saying what was sent, to whom, and the cost when known. API keys never leave the main process and are never shown in the UI.</li> |
| 107 | <li>The page's text is treated as untrusted data by the summarizer, and the summary is written into the reader with <code>textContent</code> only.</li> |
| 108 | </ul> |
| 109 | <h3>Setting up keys (never in the repository)</h3> |
| 110 | <p>Put <code>ANTHROPIC_API_KEY</code> and/or <code>OPENAI_API_KEY</code> in your environment, in the file named by <code>DBB_ENV_FILE</code>, or in <code>~/.dbbasic/env</code> (plain <code>NAME=value</code> lines). Only those names are read from a file. <b>View ▸ AI Provider</b> switches provider; Anthropic is the default. <code>DBB_AI_MODEL_ANTHROPIC</code> / <code>DBB_AI_MODEL_OPENAI</code> choose models. The defaults are small and fast — <code>claude-haiku-5-5</code> and <code>gpt-5.4-mini</code> — because a TL;DR is a one-click job; set <code>DBB_AI_MODEL_ANTHROPIC=claude-opus-5-5</code> for richer summaries at roughly 40× the cost. See <code>.env.example</code>.</p> |
| 111 | <h3>Automation</h3> |
| 112 | <p><code>reader.open {tab?, ai?, acknowledge?, wait?}</code> opens the reader; the page text is sent to a provider <b>only</b> when <code>acknowledge: true</code> is passed. <code>ai.status</code> and <code>ai.provider {provider}</code> read and switch the provider. <code>DBB_AI_CONSENT=1</code> pre-answers the consent prompt for scripted runs.</p> |
| 113 | |
| 114 | <h2 id="downloads">Downloads</h2> |
| 115 | <p>A download opens the standard macOS Save dialog with the file name the site suggested (made safe: path separators and control characters are replaced, so a hostile name can't reach outside the folder you pick). While it runs, the status line shows <b>⬇ Downloading name — 1.2 MB of 3.0 MB</b>; when it ends a toast says it was <b>saved</b> (with the x402 amount if the download was paid for) or <b>failed</b>. <b>File ▸ Show Last Download in Finder</b> and <b>Show Downloads Folder</b> take you to the file. Downloads are never opened automatically, and on macOS each file is marked as downloaded from the internet (the quarantine attribute), so Gatekeeper vets anything you later run. <code>downloads.list</code> in the automation API lists them; <code>DBB_DOWNLOAD_DIR=/some/folder</code> skips the dialog and saves there, for scripted runs.</p> |
| 116 | |
| 117 | <h2 id="loading">Loading indicators</h2> |
| 118 | <p>Each tab shows what it is doing, and the status line at the bottom left says it in words: <b>waiting</b> (request sent, no answer yet), <b>receiving</b> (with the bytes so far), <b>redirecting</b>, a site's <b>bot check</b>, an <b>x402 payment</b> (needed, paying, paid), <b>slow</b> (still waiting after 6 s), <b>failed</b> or <b>offline</b>. These come from real signals — what our own network layer and the payment engine see — so DNS, TCP and TLS, which happen inside Chromium, appear as "waiting" rather than as invented phases.</p> |
| 119 | <p>The animations follow your system's "Reduce motion" accessibility setting (on macOS: System Settings ▸ Accessibility ▸ Display): with it on, each state shows a still frame. <b>View ▸ Loading Animations</b> lets you override that with Always or Never.</p> |
| 120 | |
| 121 | <h2 id="x402">x402 payments</h2> |
| 122 | <p>When a server answers <code>402 Payment Required</code>, the browser reads the price <i>before</i> paying, applies your spending policy, and either pays, asks you, or refuses.</p> |
| 123 | <ul> |
| 124 | <li><b>Auto-approve</b> below the policy threshold (default $0.05); <b>ask</b> above it, with a native dialog showing the price; <b>refuse</b> unknown tokens/networks.</li> |
| 125 | <li>Every decision is visible: a toast, a row in the x402 inspector (request, challenge, decision, signed authorization, settlement), and the session spend meter.</li> |
| 126 | <li>Real settlement happens on Base Sepolia testnet. Use <b>Fund</b> to get testnet USDC; <b>Refund</b> returns the merchant wallet's balance to you.</li> |
| 127 | </ul> |
| 128 | |
| 129 | <h2 id="passwords">Password manager</h2> |
| 130 | <p>Click <b>Passwords</b> to create a vault. It is one encrypted file (scrypt key derivation + AES-256-GCM) on this computer, protected by a master password. <b>There is no recovery</b> if you forget it, and nothing is uploaded anywhere.</p> |
| 131 | <h3>Saving</h3> |
| 132 | <p>Sign in to any site. After you submit, a bar offers <b>Save</b> (or <b>Update</b> if the password changed). The offer survives the redirect after login. Only real keyboard/mouse submissions trigger it — a page can't fake one.</p> |
| 133 | <h3>Signing in</h3> |
| 134 | <p>On a page with a login form and a saved login for that <i>exact</i> site, a bar offers <b>Sign in as …</b> (fill and submit) or <b>Fill</b>. Nothing is filled until you click. The Passwords panel also lists this site's logins, lets you save one manually, generate a strong password, and delete entries.</p> |
| 135 | <h3>How it stays safe</h3> |
| 136 | <ul> |
| 137 | <li><b>Exact origin matching:</b> scheme + host + port must all match. <code>www.example.com</code> never fills <code>example.com</code>; lookalike domains never match.</li> |
| 138 | <li><b>Secrets stay out of the UI:</b> the page hands a submitted login straight to the main process, and fills go main → page. The browser chrome only ever sees usernames and origins.</li> |
| 139 | <li><b>Auto-lock</b> after 10 minutes of inactivity; <b>Lock</b> in the panel locks immediately.</li> |
| 140 | </ul> |
| 141 | <h3>Standalone</h3> |
| 142 | <p>The vault is also a stand-alone package with a CLI — <code>packages/vault</code>:</p> |
| 143 | <pre>npm start -w @dbbasic/vault -- init |
| 144 | npm start -w @dbbasic/vault -- add https://askrobots.com dan --generate 24 |
| 145 | npm start -w @dbbasic/vault -- get askrobots.com # prints the password only |
| 146 | # set DBB_VAULT=/path/to/vault.json to use a specific file, DBB_VAULT_PASSWORD for scripts</pre> |
| 147 | <div class="note">The browser's vault file lives in the app's data folder (override with <code>DBB_VAULT</code>). Point the CLI at the same file to share it.</div> |
| 148 | |
| 149 | <h2 id="automation">Automation API</h2> |
| 150 | <p>Drive this browser from scripts, tests and agents — the same window you are looking at, with payments and the vault as first-class citizens. It is <b>off by default</b>. Start the browser with:</p> |
| 151 | <pre>DBB_CONTROL=1 npm start -w @dbbasic/browser # listens on 127.0.0.1:9777 (DBB_CONTROL_PORT to change)</pre> |
| 152 | <p>The URL and a per-launch bearer token are written (mode 0600) to <code>~/.dbbasic/control.json</code>. Call <code>POST /rpc</code> with <code>{"method": "…", "params": {…}}</code>; the answer is <code>{"ok": true, "result": …}</code> or <code>{"ok": false, "error": {"code", "message"}}</code>.</p> |
| 153 | <pre>TOKEN=$(jq -r .token ~/.dbbasic/control.json) |
| 154 | curl -s -H "Authorization: Bearer $TOKEN" -d '{"method":"page.goto","params":{"url":"askrobots.com"}}' http://127.0.0.1:9777/rpc</pre> |
| 155 | <p>Or use the bundled client (<code>apps/browser/scripts/dbb.mjs</code>):</p> |
| 156 | <pre>import { connect } from "./scripts/dbb.mjs"; |
| 157 | const b = await connect(); |
| 158 | await b.call("page.goto", { url: "https://askrobots.com/login" }); |
| 159 | await b.call("login"); // fills + submits the saved login; you never see the password |
| 160 | await b.call("page.waitFor", { text: "Dashboard" }); |
| 161 | const { spent } = await b.call("x402.spent");</pre> |
| 162 | <p>Every method takes an optional <code>tab</code> (id from <code>tabs.list</code>); the default is the active tab.</p> |
| 163 | <table> |
| 164 | <tr><th>Method</th><th>Params → result</th></tr> |
| 165 | <tr><td>status</td><td>tabs, approval policy, spend, vault state</td></tr> |
| 166 | <tr><td>tabs.list / new / close / activate</td><td><code>new</code>: <code>{url?, activate?, wait?}</code></td></tr> |
| 167 | <tr><td>page.goto</td><td><code>{url, wait?, settle?}</code> — waits for the load to finish (default); with <code>settle</code> it returns the <a href="#settled">finished-loading verdict</a> instead</td></tr> |
| 168 | <tr><td>page.settle</td><td><code>{timeoutMs?, quietMs?, frames?, frameTimeoutMs?, minText?, blankWaitMs?}</code> — wait until the page has <a href="#settled">really finished loading</a> and say why</td></tr> |
| 169 | <tr><td>page.back / forward / reload</td><td><code>{wait?}</code></td></tr> |
| 170 | <tr><td>page.text / html</td><td><code>{selector?}</code> → page text / HTML</td></tr> |
| 171 | <tr><td>page.eval</td><td><code>{js}</code> → <code>{value}</code> (JSON-serializable)</td></tr> |
| 172 | <tr><td>page.forms</td><td><code>{includeHidden?, limit?}</code> → the page's <code>fields</code>, <code>buttons</code> and <code>forms</code>. Each field has a <code>ref</code> (a short name such as <code>e3</code> that click, hover and type accept), its label, type, <code>required</code>, <code>group</code>, options and current value. Passwords, card and one-time-code fields, hidden fields and files are listed with <code>sensitive: true</code>, the reason and whether they are filled, and <b>never their value</b>. Only the top document is read; <code>frames</code> says how many frames there are</td></tr> |
| 173 | <tr><td>page.find</td><td><code>{text? | label?, role?, includeHidden?, limit?}</code> → <code>{total, matches}</code>: elements whose words, label, placeholder or name match (best match first), each with a <code>ref</code>, role, text, address for links, and position. A <code>ref</code> that has left the page is an error (<code>no-element</code>), never a click on something else; refs do not survive a navigation</td></tr> |
| 174 | <tr><td>page.click</td><td><code>{ref | selector}</code> or <code>{x, y}</code> — a <b>real</b> trusted click</td></tr> |
| 175 | <tr><td>page.type</td><td><code>{ref? | selector?, text, clear?}</code> — real text input; replaces content unless <code>clear:false</code></td></tr> |
| 176 | <tr><td>page.press</td><td><code>{key}</code> — <code>Enter</code>, <code>Tab</code>, <code>Escape</code>, arrows, or a character</td></tr> |
| 177 | <tr><td>page.waitFor</td><td><code>{selector?, text?, url?, timeoutMs?}</code> — all given conditions must hold</td></tr> |
| 178 | <tr><td>page.screenshot</td><td>→ <code>{png (base64), width, height}</code></td></tr> |
| 179 | <tr><td>chat.send / events / confirm / stop / clear / mode / state</td><td>the <a href="#chat">assistant chat</a>. <code>chat.send {text, mode?, wait?}</code> sends one message and waits until the assistant is done (<code>wait:false</code> returns at once; follow with <code>chat.events {since}</code>). An action that needs an answer shows up as a <code>confirm</code> event with an <code>id</code>; answer it with <code>chat.confirm {id, ok}</code>. <code>mode</code> is <code>ask</code> (every action asks) or <code>auto</code> (only risky ones). Off while the caller network is on</td></tr> |
| 180 | <tr><td>mcp.state / connect / cancel / disconnect / refresh / tools</td><td>connections to other services (<a href="#connections">see below</a>). <code>mcp.connect {id, open?, via?, wait?}</code> starts an OAuth sign-in and opens the consent page in a tab of this browser (the redirect back is caught inside it); <code>via:"system"</code> opens the person's own browser and listens on 127.0.0.1 instead; <code>open:false</code> returns <code>{authorizeUrl}</code> and listens, so a script can do what the person's browser would. <code>mcp.refresh {id}</code> refreshes the access token now and says whether the server also issued a new refresh token (<code>rotated</code>), never returning a token. <code>mcp.state</code> never contains a token. Off while the caller network is on</td></tr> |
| 181 | <tr><td>menu.last / menu.pick</td><td>the right-click menu shown last (<code>wcId</code> and its <code>items</code>, each an <code>id</code> and <code>label</code>), and <code>pick {id}</code> runs one of its items exactly as a click would. Only items that were in that menu and enabled can be picked. In background mode (and with <code>DBB_RECORD_MENUS=1</code>) a menu is recorded instead of shown, and a <code>context-menu</code> event lists its items</td></tr> |
| 182 | <tr><td>resources.state / clearCache</td><td>what the browser is using, the same numbers as the <b>Memory</b> panel in the status bar: <code>totalMemoryMB</code>, <code>byType</code> (pages, browser, graphics), <code>tabs</code> (each with <code>memoryMB</code>, <code>cpu</code>, whether its process is shared), <code>cacheBytes</code> and <code>disk</code> (the data folder and what it is made of). On a Mac, memory is the physical footprint (what Activity Monitor shows, including memory the system has compressed), not resident size, which can hide hundreds of MB. <code>clearCache</code> empties the cache and keeps logins</td></tr> |
| 183 | <tr><td>bookmarks.list / add / has</td><td>bookmarks are your saved links on askrobots.com, over the same connection as the assistant's tools. <code>bookmarks.list {refresh?}</code> gives the local copy, or with <code>refresh:true</code> fetches the newest 100 from the service; <code>bookmarks.add {url, title?}</code> saves one (private, where the server's entry says saved links go) and never twice; <code>bookmarks.search {q}</code> searches all your links on the service (what you typed is sent, nothing else); <code>bookmarks.check {url}</code> asks the account about a page's site (once every ten minutes per site; the browser does it on its own when you open a page it does not know, unless the setting in the list is off, <code>bookmarks.setCheck {on}</code>); <code>bookmarks.has {url}</code> is answered from the local copy. The list loads once when the browser opens with a saved sign-in (not in scripted or background runs), when it is opened, after saving and after signing in</td></tr> |
| 184 | <tr><td>keep.tab / list / get / remove</td><td>Keep: <code>keep.tab {tab?, reason?, close?, bookmark?}</code> keeps a copy of a page (a picture of what is on screen and its text) on this computer, saves it as a bookmark when askrobots is connected and uploads the picture and the text to your askrobots Files (private, in the category and project the server's entry names, named "<title> (<site>, <date>)"), and closes the tab (pages with a sign-in form are refused). A server entry's <code>browserOnly</code> tools (here <code>upload_file</code>) are used by the browser itself and never offered to the assistant; <code>keep.list {q?}</code> lists copies, newest first, or those whose title, address, reason, tags or text contain every word of <code>q</code>; a copy opens at <code>dbb-kept://<id>/</code></td></tr> |
| 185 | <tr><td>vault.state / unlock</td><td><code>unlock</code>: <code>{master}</code></td></tr> |
| 186 | <tr><td>login</td><td><code>{id?, submit?, wait?}</code> — fill (and submit) the saved login for the tab's exact origin</td></tr> |
| 187 | <tr><td>x402.spent / receipts</td><td>session spend; full ledger</td></tr> |
| 188 | <tr><td>x402.events</td><td><code>{since}</code> → <code>{events, next}</code> — every quote, decision, payment and refusal</td></tr> |
| 189 | <tr><td>DBB_BACKGROUND=1</td><td>environment, not a method: automation that never takes the screen. The window is shown without focus, moved off-screen, made transparent and click-through (it is still drawn, unlike a hidden or minimized window), the app stays out of the Dock, and nothing raises or focuses it, including real input. For scripted runs on a machine someone is using</td></tr> |
| 190 | <tr><td>ext.<name></td><td>methods added by local extensions: <code>DBB_EXTENSIONS=/abs/one.mjs:/abs/two.mjs</code> loads ES modules that export <code>register(api)</code> and add methods with <code>api.method(name, handler)</code>. They run with the browser's own privileges, load only from that variable, and an extension that fails to load stops the browser starting. <code>status</code> lists the loaded files</td></tr> |
| 191 | <tr><td>net.provider</td><td><code>{enabled?, userAgent?, answerTimeoutMs?, cookies?, limits?}</code> — a network layer <em>you</em> supply: while on, the browser makes no request of its own; each one waits for you. <code>userAgent</code> is required to turn it on (your identity, never this browser's). <code>answerTimeoutMs</code> (1–120 s, default 20 s) is the one bound on waiting for you. Needs a profile of its own (start with <code>--user-data-dir=…</code>) because every visit clears stored data. While on: WebSockets and WebRTC are refused, and <code>login</code>, the reader, payments and refunds are switched off. <code>cookies: "visit"</code> keeps cookies for one visit only (default <code>"off"</code>: none stored, none sent). <code>limits: {requests?, bytes?}</code> (0 = none) stops a visit that asks for too much: past a limit the next request fails at once with a reason, and a response already under way is never cut off. Permission prompts, downloads and pop-ups are refused while the mode is on (a download is still reported as one). At most 64 requests wait at once. <b>Known gap:</b> WebTransport (QUIC) cannot be switched off from inside Electron; deny UDP egress for the user the browser runs as if that matters</td></tr> |
| 192 | <tr><td>net.pending</td><td><code>{afterId?, waitMs?}</code> — requests waiting for an answer (<code>id, url, method, headers, bodyBase64?, follows, destination, navigate</code>); waits up to <code>waitMs</code> for one to arrive</td></tr> |
| 193 | <tr><td>net.answer</td><td><code>{id, status, headers?, bodyBase64 | bodyText, statusText?}</code> — answer a request. A 3xx goes back to the page, which asks again, so every hop is yours. The body is the body to show: transport headers and <code>Set-Cookie</code> are dropped (state is yours)</td></tr> |
| 194 | <tr><td>net.fail</td><td><code>{id, kind, detail?}</code> — refuse a request; <code>kind</code> is one of the failure kinds below. The load ends with that reason and <code>source: "caller"</code></td></tr> |
| 195 | <tr><td>page.load</td><td><code>{url, status, headers?, bodyBase64 | bodyText, redirects?, settle?}</code> — load a main document you already fetched, at its final address, so relative links resolve and the facts list the redirects</td></tr> |
| 196 | <tr><td>page.hover</td><td><code>{ref | selector | x,y}</code> — move the real pointer without clicking (hover states, link addresses)</td></tr> |
| 197 | <tr><td>net.policy</td><td><code>{blockWebSockets?}</code> — refuse WebSockets before any connection is opened (they bypass the network layer); no params reads the policy</td></tr> |
| 198 | <tr><td>downloads.list</td><td>every download this session: name, host, bytes, state, saved path, amount paid</td></tr> |
| 199 | <tr><td>reader.open / ai.status / ai.provider</td><td>the AI Reader — see <a href="#reader">above</a></td></tr> |
| 200 | <tr><td>x402.approval</td><td><code>{mode: "ask"|"auto"|"deny", maxUsd}</code> — who answers payment prompts; call with no params to read</td></tr> |
| 201 | </table> |
| 202 | <h3 id="chat">Assistant chat</h3> |
| 203 | <p>Press <b>⌘J</b> (or <b>Chat</b>) for a side panel where you can talk to an assistant about the page you are on, and ask it to do things: find something, read a page, fill in a form, open a page. It uses the same tools as the automation API (<code>page.forms</code>, <code>page.find</code>, click, type…), run inside the browser.</p> |
| 204 | <ul> |
| 205 | <li><b>Which model.</b> The picker at the top of the Assistant panel chooses the assistant's model, from the providers you have set up, and is remembered. The assistant defaults to <code>claude-sonnet-5-5</code>: it reads pages and chooses tools over many steps, where the smallest model makes needless mistakes. The picker shows each model's cost next to Haiku's (Sonnet about 20×). It applies to the assistant only; the reader's summaries keep the model above. The automation API's <code>chat.model</code> does the same.</li> |
| 206 | <li><b>You approve what it does.</b> In <i>Ask first</i> mode every action (open, go to, click, type, choose, press a key) waits for <b>Do it</b> or <b>Skip</b>. In <i>Auto</i> mode only a short allow-list runs without asking: switching tab, going back, keys that only move, typing into an ordinary field, choosing in a dropdown, and clicking a link to a site that is already open, a checkbox or a radio button. Everything else asks: any other click (a button need not say anything scary to be risky), Enter, and opening a site that is not open. A click that submits a form or is about buying, paying, deleting or sending is always marked risky.</li> |
| 207 | <li><b>After it has read your private data</b> from a connected service (contacts, notes, tasks), typing and opening addresses ask in every mode, because a page you are on could try to talk the assistant into copying what it read into the page.</li> |
| 208 | <li><b>It never fills password, card number or one-time-code fields</b>, and their values are never put in the field lists it reads.</li> |
| 209 | <li><b>Pages are untrusted, and the assistant is told whose words are whose.</b> Only what you type is an instruction. Everything a tool returns (page text, field names, tab titles, results from your accounts) arrives with a line saying where it came from and that it is not from you, between tags that carry a random word made for that conversation, so a page cannot forge the end of the block or a message of its own. The system prompt says how to tell the two apart and to ignore anything between those tags that tries to give orders.</li> |
| 210 | <li><b>What leaves your machine:</b> your messages and what the assistant reads from your open pages go to the model, and the first message per model each session asks first, naming where. Every finished run is written to the event log with the model and the tokens used.</li> |
| 211 | <li><b>Which model:</b> the same keys as the AI Reader (<code>ANTHROPIC_API_KEY</code>, <code>OPENAI_API_KEY</code> in the environment or <code>~/.dbbasic/env</code>). To use a model on this machine or your network, set <code>DBB_AI_BASE_URL</code> to an OpenAI-compatible endpoint (https, or http to this machine or a private network only). Switched off while the caller network is on.</li> |
| 212 | </ul> |
| 213 | <h3 id="connections">Connections to other services (MCP)</h3> |
| 214 | <p>The assistant can use tools from services you sign in to. In the chat panel, <b>Connect</b> opens the service's consent page in a tab of this browser (you sign in to the service there once if you have not; the password manager can fill it); the redirect back is recognised inside the browser, so there is no system browser and nothing listens on a port, and the tokens stay in the browser's main process, encrypted with your operating system's keychain (or, if that is unavailable or <code>DBB_MCP_STORE=memory</code> is set, only in memory until you quit). The browser signs in the standard way: it reads the server's published sign-in documents, registers itself as a public client, and uses PKCE; there is no secret to leak.</p> |
| 215 | <ul> |
| 216 | <li><b>Which tools:</b> a server adds only the tools its entry lists, not everything it offers. Tools that only read run when the assistant asks; every other tool is asked about every time, even in Auto mode.</li> |
| 217 | <li><b>Which servers:</b> askrobots.com is built in. Add more in <code>mcp-servers.json</code> in the browser's data folder (or the file named by <code>DBB_MCP_SERVERS</code>): <code>[{"id": "notes", "name": "My notes", "url": "https://…/mcp", "tools": ["search", "add"], "readOnly": ["search"], "fixedArgs": {"add": {"project": "inbox"}}, "dropFields": {"search": ["private"]}}]</code>. <code>fixedArgs</code> are forced on a tool whatever the assistant asks for, and <code>dropFields</code> are removed from results before the assistant sees them. <code>extraScopes</code> are permissions asked for at sign-in that the server does not publish (askrobots: <code>files:upload</code>, for saving kept pages in your Files); a server that refuses them is asked again without them, and the panel says when the current sign-in lacks one (connect again to give it). A file entry with the same id replaces the built-in one, so to keep saved askrobots links in one project, copy the askrobots entry and add <code>"project_id"</code> to its <code>fixedArgs</code> for <code>create_link</code> and <code>list_links</code>. An entry that is not valid is skipped, with the reason printed at start-up.</li> |
| 218 | <li>What a server returns is untrusted data, like page text. Disconnecting forgets the tokens and asks the server to revoke them.</li> |
| 219 | </ul> |
| 220 | <h3 id="settled">Knowing when a page has finished loading</h3> |
| 221 | <p>Waiting for "loaded", or for the network to be quiet for half a second, or sleeping a fixed time, is a guess: pages that stream, poll or build themselves late fool it, and when it gives up all you learn is that time passed. <code>page.settle</code> (or the <code>settle</code> option of <code>page.goto</code>) decides from what the browser actually observes, and answers <b>two separate questions</b>:</p> |
| 222 | <ul> |
| 223 | <li><b><code>rule</code> — what ended the wait.</b> <code>frames-match</code> (everything below held and two frames a moment apart were identical), <code>quiet</code> (same, with the frame test off), <code>animating</code> (everything held but the page keeps changing by itself), or <code>deadline</code>, <code>navigation-failed</code>, <code>crashed</code>, <code>download</code>, <code>payment</code>.</li> |
| 224 | <li><b><code>outcome</code> — what happened.</b> <code>ok</code>, <code>error-status</code> (with the number; <code>slowDown: true</code> for 429), <code>blank</code>, <code>failed</code> (with a <code>failure.kind</code> such as <code>could-not-find-site</code>, <code>could-not-connect</code>, <code>certificate</code>, <code>redirect-loop</code>, <code>offline</code>, <code>timed-out</code>, <code>blocked</code>, <code>caller-silent</code> — the caller-supplied network layer did not answer in time — or <code>other</code>; and <code>failure.source</code>: <code>observed</code> when the browser saw it, <code>caller</code> when the caller said so), <code>crashed</code>, <code>bot-check</code>, <code>payment-required</code>, <code>not-a-page</code> (a download), <code>deadline</code>.</li> |
| 225 | </ul> |
| 226 | <p>A page counts as settled when the load event has fired; no request is in flight (apart from long-lived streams, which a finished page can hold open and which are ignored and counted in <code>streams</code>); nothing has moved on the network for <code>quietMs</code>; web fonts are in; the visible images are decoded; and two frames <code>frameGapMs</code> apart match. At the deadline the call still returns, with <code>blockedBy</code> naming what was unmet (for example the one request that never answered). The verdict also carries <code>waitedMs</code>, <code>status</code>, the final URL and title, the server <code>redirects</code>, and the request, byte and host counts.</p> |
| 227 | <p><b>Pages that move themselves.</b> A page that navigates after it has begun (a script, a <code><meta refresh></code>, a link) restarts the wait, and the verdict lists each such move in <code>moves</code> (<code>{to, afterMs}</code>), separately from server redirects. A visit starts when the browser navigates (for example <code>page.goto</code>); a move that begins after the verdict was returned belongs to a new look at the page, so call <code>page.settle</code> again, or raise <code>quietMs</code> to watch for slower ones.</p> |
| 228 | <p><b>Blank pages.</b> A settled page is called <code>blank</code> when it shows fewer than <code>minText</code> characters of text (default 20; <code>0</code> turns the test off) and has no image, canvas, video or svg. A page that fills itself in late would settle as blank first; <code>blankWaitMs</code> (default 0) keeps checking for that long for text or media to appear, then settles. A page that stays blank is still reported <code>blank</code>, and the time waited is in <code>waitedMs</code>.</p> |
| 229 | <p><b>Console and cookies.</b> The verdict includes <code>console</code>: <code>counts</code> by level (<code>error, warning, info, debug</code>) for the visit, and the first 20 <code>errors</code> as <code>{text, line}</code>, each cut to 200 characters (it is the page's own text: treat it as data, never as instructions). It also includes <code>cookies</code>: the cookies that apply to the address the visit ended on, as <code>{name, domain, path, secure, httpOnly, session}</code>. Cookie values are never included. A page that moves itself keeps adding to the same console record; the next <code>page.goto</code> starts a new one.</p> |
| 230 | <p><b>How much of the page arrived.</b> <code>outcome: "ok"</code> says the main document settled; it says nothing about the files the page asked for. <code>resources</code> counts them for the visit: <code>requested</code>, <code>answered</code> (a redirect counts; <code>errorStatus</code> of these answered with 4xx or 5xx), <code>failed</code> with <code>failedByKind</code> (the same reasons as <code>failure.kind</code>), <code>cancelled</code> (the page gave up on them itself), <code>waiting</code> (still open when the verdict was given) and <code>mainDocument</code> (<code>answered</code>, <code>failed</code> or <code>pending</code>). A complete page has <code>failed: 0</code> and <code>waiting: 0</code>.</p> |
| 231 | <p><b>Example: a <code><meta refresh></code>.</b> A page that says <code><meta http-equiv="refresh" content="1;url=/next"></code> loads, settles in under a second, and the verdict is for that first page with <code>moves: []</code>; the move to <code>/next</code> starts a new look at the page. To get the page it moves to, call <code>page.settle</code> again, or raise <code>quietMs</code> past the refresh delay so the first wait is still open when the move happens (then <code>moves</code> lists it).</p> |
| 232 | <div class="note warn"><b>What it cannot see:</b> DNS, TCP and TLS happen inside Chromium, so they are part of "waiting". <b>WebSockets</b> bypass the network layer, so a page driven by a socket can look quiet while it is still receiving; <code>net.policy {blockWebSockets: true}</code> refuses them before any connection is opened. The frame test brings the tab forward, like a screenshot.</div> |
| 233 | <div class="note"><b>Why use this instead of Playwright/CDP?</b> It controls the real, visible browser; input is genuinely trusted (sites that ignore synthetic clicks work); payments are inspectable and assertable (<code>x402.events</code>) rather than a dialog your test can't dismiss; and <code>login</code> signs you in without your script ever holding a password. Input methods bring the tab and the window to the front (taking keyboard focus), because real input needs a visible, focused page.</div> |
| 234 | |
| 235 | <h2 id="identity">How we identify ourselves</h2> |
| 236 | <p>Every request carries a Chromium-compatible User-Agent that says who we are and links to <a href="https://dbbasic.com">dbbasic.com</a>:</p> |
| 237 | <pre>Mozilla/5.0 (…) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130… Safari/537.36 dbbasic-browser/0.1.0 (+https://dbbasic.com)</pre> |
| 238 | <p>This is the same convention Edge and Opera use: the engine really is Chromium, so the usual tokens stay, and our own token goes on the end. We do not pose as Firefox or Chrome — it would be untrue, and it would contradict the client hints, JavaScript APIs and TLS handshake a site can also see.</p> |
| 239 | <p>We do send what a real Chromium navigation sends: <code>Sec-CH-UA</code> client hints (taken from the engine itself, so they always match <code>navigator.userAgentData</code>), correct <code>Sec-Fetch-*</code> metadata, and a <code>Referer</code> that follows the page's referrer policy.</p> |
| 240 | <div class="note warn"><b>Some sites will still refuse us.</b> A few large sites (eBay, for one) run bot management that rejects embedded-Chromium browsers at the edge — we measured the same HTTP 403 with our own network layer switched off, with a bare Chrome User-Agent, and with a Firefox one, while Firefox on the same machine was served. That is the site's decision; we don't try to evade it. Use <b>File ▸ Open Page in Default Browser</b> for those pages.</div> |
| 241 | <p>Debugging: <code>DBB_USER_AGENT="…"</code> replaces the User-Agent entirely, and <code>DBB_NATIVE_NETWORK=1</code> turns off request interception (and x402 payments) so Chromium's own loader makes every request.</p> |
| 242 | |
| 243 | <h2 id="security">Security model</h2> |
| 244 | <ul> |
| 245 | <li>The automation API binds <b>127.0.0.1 only</b>, requires the bearer token on every request, refuses any request carrying an <code>Origin</code> header (so a web page can't drive it) and any non-loopback <code>Host</code> (DNS rebinding). A <b>🤖</b> chip shows whenever it is on.</li> |
| 246 | <li>Automation that relaxes payment approval is never silent: each decision raises a toast and an inspector/event-log entry. The spending policy's hard caps still apply on top.</li> |
| 247 | <li>Treat the token like a password: anyone who has it can drive a browser that holds a wallet key and (while unlocked) your vault. Keep <code>~/.dbbasic/control.json</code> private; leave the API off when you don't need it.</li> |
| 248 | <li><b>Redirects are visible to the page:</b> a redirect is handed back to the page, which re-requests the new address — so the address bar, the page's origin and the password manager's origin matching always reflect where you actually are, and each hop gets its own payment decision.</li> |
| 249 | <li>The wallet key for testnet payments is a hot key in <code>.env</code>. Never fund it with real money. See <code>SECURITY.md</code>.</li> |
| 250 | </ul> |
| 251 | </main> |
| 252 | </body> |
| 253 | </html> |