r5d-browser

r5d-browser starts stable Google Chrome with a dedicated, persistent profile on a Mac and connects it to r5d.dev. Sign in to sites in the opened browser normally; agents control Chrome over a loopback-only debugging connection without moving the real system pointer or taking keyboard focus.

npm install -g @ricsam/r5d-browser
r5d-browser start

Install stable Google Chrome before starting the browser. r5d-browser resolves the executable in this order:

1. --chrome-path <path>
2. R5D_BROWSER_CHROME_PATH
3. /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
4. ~/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

For example:

r5d-browser start --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

The profile is stored under ~/.r5d/browser/chrome-profile. The previous Chrome for Testing profile at ~/.r5d/browser/profile is preserved but is not migrated automatically, so sign in again the first time you use the new profile. Browser binaries previously installed under ~/.r5d/browser/browsers are also left untouched, but new versions of r5d-browser do not use them. Completed downloads are retained under ~/.r5d/browser/downloads; agents can list them and copy a selected file into the active session's artifacts. That artifact is then synchronized to every connected worker. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.

Agents read pages through browser_read_page, an accessibility outline with stable element refs ([ref=e12]) on interactable elements and [box=x,y,w,h] viewport coordinates on everything visible. Refs feed the one-call interaction tools: browser_mouse_click clicks a ref (scrolled into view, with actionability checks) or an x/y point, browser_form_input sets values on text inputs, selects, checkboxes, and contenteditable elements with trusted events that controlled (React-style) components honor, and browser_scroll scrolls an element into view or dispatches trusted wheel input. Same-origin iframe content appears inline with frame-prefixed refs such as f1e3; cross-origin frame content may be omitted. Refs come from the most recent snapshot of a tab, so agents re-read the page after navigations or large re-renders. browser_wait_for waits for a selector, visible text, a URL glob, or a load state instead of sleeping, and browser_keyboard_type has a keys mode that presses each character as a real key event (up to 500 characters per call) for type-ahead widgets — characters without key codes, such as emoji, still fall back to text insertion. Screenshots capture the viewport by default; fullPage: true captures the scrollable page up to 4000 CSS px of height.

Agents running JavaScript in a page can save captured text straight into the active session's artifacts by calling r5dCreateArtifact(filename, content), which takes two strings and must be called before the agent's code returns. Each captured file is written to the session artifacts in r5d.dev, synchronized to every connected worker, and reported back as a $R5D_ARTIFACTS_DIR path; a single call may create at most 32 files totalling 4 MiB. The function is passed into the agent's code rather than assigned to window, so pages can neither call it nor use it to detect automation.

Agents can also create loopback-only TCP port forwards from this Mac to the worker bound to a chat. For example, a forward can map Chrome's localhost:4323 to 127.0.0.1:3232 on that worker. The relay preserves raw TCP traffic, including HTTP, HTTPS, WebSockets, HMR, and SSE; it never exposes a public listener or permits an arbitrary target host.

Port forwards remain active across agent turns and r5d.dev control-connection reconnects. They are owned by the running r5d-browser process, so restarting that process ends them. Agents can list and stop forwards, and the user can inspect or stop them from Settings.