Browser agent

Browser agent

The built-in browser agent lets Holaryn research websites, follow links, complete forms, work across
tabs and frames, upload or download files, take screenshots/PDFs, and preserve an inspectable action
trace. It ships as part of Holaryn: you do not install Node.js, run npx, configure an MCP server, or
restart the app.

Try the local demo

holaryn browser demo

The demo opens a local synthetic form, finds its fields by accessible label and role, enters a
value, approves the final simulated submission, verifies the result, and prints the trace path. It
does not contact a website.

Useful diagnostics:

holaryn browser status
holaryn browser status --json
holaryn browser repair
holaryn browser trace <session-id> --output browser-trace.json

The first real use may download Holaryn's supported Chromium build. The download is performed by the
driver bundled with Holaryn, then the driver and browser executable are hashed. repair repeats that
process without requiring Node or npx and does not remove browser profiles.

Ask the agent

Example research prompt:

Open the product documentation, compare the installation pages, and cite the pages you used.
Visit no more than five pages and do not submit anything.

A result may look like:

The desktop installer bundles the host, while the Python install uses uv. Sources: “Installation”
(https://…/installation) and “Desktop app” (https://…/desktop). I visited 2 unique pages.

Example form prompt:

Open the local demo form, fill Name with “Juan”, attach sample.txt, and stop before the final
submit so I can approve it.

Holaryn observes accessible roles and names first. The final submit and upload appear as approval
requests showing the tool, locator, origin, and selected file name. Denial leaves the form open.

Browser page in web and desktop

Choose Browser in the primary navigation. The page provides:

• an ephemeral or named persistent profile choice;
• a visible-window option for manual takeover;
• a session selector and explicit status;
• current page title and URL;
• a live screenshot with useful alternative text;
• a list of semantic controls from the page's accessibility information;
• Pause / take over, Resume automation, and Stop browser;
• a downloadable redacted JSON trace.

Every control is reachable by keyboard and uses native headings, labels, buttons, status regions,
and lists so screen readers do not depend on the screenshot.

Ephemeral and persistent profiles

Ephemeral is the safe default. It creates an isolated context and discards cookies and session state
when stopped.

A persistent profile retains site cookies/session state under its name. Select it only when you
intend later sessions to reuse that login. A profile cannot be live in two sessions at once. Do not
share a persistent profile across people, projects, or trust boundaries.

Holaryn traces the profile name and browser actions but never raw cookies, authorization headers,
password-field contents, or credential values.

Approvals and untrusted pages

Web pages are external data, not instructions to Holaryn. Page text, hidden/visible DOM, accessibility
snapshots, frames, and research excerpts are labeled untrusted and screened for prompt injection.
A page cannot change autonomy, policy, profile, or approval state.

Interaction is conservative:

• role/name, label, and visible text locators come before CSS/test ids;
• coordinate clicks use an explicit x,y point in the current viewport, are disabled unless
  enabled as visual fallback, reject out-of-window points, and always require approval;
• typing, upload, final submit, browser control, and other interaction calls enter the normal
  approval policy;
• uploads must stay inside allowed workspace roots;
• origins can be allowlisted or denied by policy;
• research deduplicates URLs, respects robots.txt and rate limits, and has a page cap;
• CAPTCHAs, paywalls, anti-bot bypass, and access-control bypass are not supported.

Downloads are recorded with size and SHA-256 and remain quarantined. Inspect a download before
opening or moving it into a trusted workspace. Browser-created screenshots and PDFs stay in the
session artifact directory; screenshots mask password inputs.

Traces and recovery

Trace entries include timestamp, action, locator, URL origin, semantic/DOM/visual method, approval
decision, outcome, error, and artifacts. Entered text and credentials are redacted; uploads record
only the file name.

Closing or reloading the Holaryn web page does not stop browser work. The browser session belongs to
the host, so the Browser page reconnects to it. Terminal states are explicit:

• stopped: completed or stopped normally;
• cancelled: cancelled by the operator;
• crashed: the browser engine exited;
• interrupted: the host restarted while the session was live.

No terminal state silently resumes. Review its trace and start a new session.

Troubleshooting

Do not delete the full Holaryn state directory to repair the browser. holaryn browser repair preserves
profiles, sessions, and traces.