Introduction

Getting Started

Mr. Browser is an open-source browser automation engine that resolves elements from plain-English intent instead of CSS selectors. This guide gets you from zero to a passing flow in about five minutes.

# Installation

The engine ships as a Docker image with a bundled dashboard, or as a lightweight SDK for Python and TypeScript.

terminal

bash

# Docker (recommended — includes engine + Chromium)
docker compose -f docker/docker-compose.yml up -d

# Build from source (requires Go 1.22+)
git clone https://github.com/aryainguz/mrbrowser.git
cd mrbrowser
make build           # produces bin/mr-browser
make install         # copies to /usr/local/bin/mr-browser

# Python SDK
pip install mrbrowser

# TypeScript SDK
npm install @mrbrowser/sdk

Tip

The Docker image bundles a Chromium installation and writes data to a volume at /app/data. The engine listens on http://localhost:7331. The SDKs talk to it over that port — nothing ever leaves your machine.

# Your first flow

Flows are plain YAML. Each step declares an intent — a human description of the element — and the engine resolves it against the DOM Accessibility Tree.

yaml

# login.yaml
name: login_admin
steps:
  - open:
      url: "https://corp-portal.internal/login"
  - type:
      target: "Email"
      value: "admin@corp.com"
  - type:
      target: "Password"
      value: "$SECRET_PASS"
      enter: true
  - wait:
      seconds: 1
  - assert:
      text_visible: "Dashboard"

# Run it

terminal

bash

$ mr-browser run login.yaml

[intent] resolving "Email"      → <input aria-label="Email">     (0.98)
[intent] resolving "Password"   → <input type="password">        (0.97)
[memory] 2 fingerprints stored  → ./mrbrowser.db
✔ login_admin — 2/2 steps passed in 2.4s

# Run with headed browser (watch it happen)
$ mr-browser run login.yaml --headless=false

# Step through interactively
$ mr-browser debug login.yaml --headless=false

Each resolution logs a confidence score and stores a structural fingerprint in the Memory Engine. If the portal's UI changes next quarter, those fingerprints are what let your flow heal itself.

Warning

Never hardcode credentials in flow files. Use $ENV_VAR references — they are resolved at runtime and redacted from all logs and fingerprints.