Browser Runtime documentation

npm install @mlola/browser-runtime
npx @mlola/browser-cli browser doctor      # every line should be green

mlola browser config init                  # writes mlola.config.json

# { "providers": {
#     "decision":  { "provider": "typesafe", "model": "jev-latest" },
#     "reasoning": { "provider": "openrouter", "model": "openai/gpt-5.6-luna" } } }

# or stay with environment variables:
export TYPESAFE_API_KEY=...                # TypeSafe is the default fast path
export OPENROUTER_API_KEY=...              # one key also runs everything: --fast openrouter

npx @mlola/browser-cli browser run \
  --goal "Download my latest invoice" \
  --url https://billing.example.com/invoices

# the run prints status, verification and the artefact
npx @mlola/browser-cli browser trace show <runId>   # every decision, action and recovery
mlola browser config show                            # which routes resolved, credentials redacted

node --version        # v22.18+ or v24.x
npx @mlola/browser-cli doctor

npm install @mlola/browser-runtime
npx @mlola/browser-cli browser doctor        # no global install needed

# or install the CLI globally:
npm install -g @mlola/browser-cli
mlola browser doctor

export TYPESAFE_API_KEY="tsk_..."
mlola browser doctor

echo 'export TYPESAFE_API_KEY="tsk_..."' >> ~/.zshrc
source ~/.zshrc

TYPESAFE_API_KEY="tsk_..." npx @mlola/browser-cli browser run \
  --goal "Download my latest invoice" \
  --url https://billing.example.com/invoices

# .env
echo 'TYPESAFE_API_KEY=tsk_...' > .env
node --env-file=.env ./node_modules/.bin/mlola browser run --goal "..."

mlola browser config init          # writes mlola.config.json
mlola browser config show          # what the file says + what actually resolved

# and if you only have an OpenRouter key, the fast path runs on it too:
export OPENROUTER_API_KEY=...
mlola browser run --fast openrouter --goal "Download my latest invoice" --url https://...

mlola browser run --provider typesafe …   # fast path (needs a key)
mlola browser run --provider keyword  …   # offline baseline, no key required

mlola browser doctor

mlola browser run \
  --goal "Download my latest invoice" \
  --url https://billing.example.com/invoices

step click → 1 (358ms, conf 0.91)
  ⤓ downloaded invoice-2026-08.pdf (invoice)
  → CLICK [1] (324ms)
step done (344ms, conf 0.99)
  ✔ verified: artifact evidence: a1 invoice-2026-08.pdf

run completed
  steps            2 in 2.1s
  verification     verified — artifact evidence: a1 invoice-2026-08.pdf
  artifacts        a1 invoice-2026-08.pdf  invoice, verified
  usage            decision 2 · planner 0 · text 0 · $0.0000
  trace            ~/.mlola/browser-runtime/runs/r_xxx/events.jsonl

export OPENROUTER_API_KEY="sk-or-..."
export MLOLA_LLM_MODEL="deepseek/deepseek-v4.1-flash"   # or openai/gpt-5.6-luna

mlola browser doctor --check-llm          # verify the key, the model and the round trip
mlola browser run --goal "…" --url https://…

export OPENAI_API_KEY="sk-..."
export MLOLA_LLM_PROVIDER=openai
export MLOLA_LLM_MODEL="gpt-5.6-luna"

# endpoint internal
export MLOLA_LLM_PROVIDER=custom
export MLOLA_LLM_BASE_URL="https://llm.internal.example/v1"
export MLOLA_LLM_API_KEY="…"

mlola browser run --llm none --goal "…" --url …    # no escalation, no planning, no text model
mlola browser trace summary <runId>               # planner calls, fast-path share, cost

npm run build && npm run build:extension
mlola browser daemon start

# chrome://extensions → Developer mode → Load unpacked → extensions/chrome
# mlola browser extension pair   → token copied to your clipboard + the two fields
# extension options → paste ws://127.0.0.1:7717/extension and the token

mlola browser extension status          # is a browser attached, and what can it do?
mlola browser run --browser-extension --goal "Download my latest invoice" --url https://…

{
  "providers": {
    "decision":  { "provider": "typesafe", "model": "jev-latest" },
    "reasoning": { "provider": "openai",   "model": "gpt-5.6-luna" }
  }
}

mlola browser config init      # write the starter file (never overwrites)
mlola browser config show     # the file, plus what actually resolved
mlola browser config show --json

npm install && npm run build
npm run demo                # headless Playwright + your own Chrome
npm run demo -- invoice     # headless only
npm run demo -- extension   # your own Chrome only (daemon + loaded extension)
mlola browser config llm    # which provider, model and key it will use

{
  "goal": "Download my latest invoice, attach it to a new reimbursement claim titled \"August travel\", then stop before submitting",
  "startUrl": "https://billing.example.com/invoices",
  "successCriteria": { "criteria": { "kind": "artifact", "documentType": "invoice" } },
  "stopBefore": ["submit claim"],
  "budgets": { "maxSteps": 30, "maxCostUsd": 0.5 },
  "browser": { "backend": "playwright", "headless": true },
  "policy": { "defaults": { "upload": "allow" } },
  "screenshot": "on-failure"
}

mlola browser run invoice-claim.json
mlola browser run --task invoice-claim.json --stop-before "submit claim,payment"

{
  "defaults": { "upload": "allow", "send_message": "ask", "purchase": "takeover" },
  "siteRules": [
    { "pattern": "*.internal.example.com", "risk": "upload", "mode": "allow" }
  ],
  "blockedOrigins": ["*.ads.example.com"],
  "restrictNavigation": false,
  "secretsRequireTakeover": true,
  "maxTypedLength": 2000
}

mlola browser run   --goal 'Download my latest invoice, attach it to a new reimbursement claim titled "August travel", then stop before submitting'   --url https://billing.example.com/invoices   --stop-before "submit claim"   --yes

mlola browser run   --goal "Sign in and open my claims list"   --url https://portal.example.com

# what you will see:
#   human needed (credential)
#   Take over the browser, finish this step, then hand control back.
#   (press Enter when done — the runtime re-observes and resumes)

mlola browser run   --goal "Download my latest invoice, then open the reimbursement portal in a new tab, sign in and attach it"   --url https://billing.example.com/invoices   --stop-before "submit"

# literal: the quoted value is typed as-is (no model call)
mlola browser run   --goal 'Enter "August travel" as the claim title'   --url https://portal.example.com/claim

# generation: configure a text provider, otherwise the runtime asks a person
export MLOLA_TEXT_BASE_URL="https://api.openai.com/v1"
export MLOLA_TEXT_API_KEY="sk-..."
export MLOLA_TEXT_MODEL="gpt-4o-mini"
mlola browser run   --goal "Write a short description of this month's travel expenses in the notes field"   --url https://portal.example.com/claim

mlola browser daemon start

TOKEN=$(cat ~/.mlola/browser-runtime/daemon/token)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json'   -d '{"goal":"Download my monthly invoice","startUrl":"https://billing.example.com/invoices","providers":{"decision":"typesafe"}}'   localhost:7717/v1/runs

# crontab -e — every 1st at 08:00
0 8 1 * * cd /srv/mlola && TYPESAFE_API_KEY=tsk_... /usr/bin/node ./node_modules/.bin/mlola browser run --no-human --yes --goal "Download my monthly invoice" --url https://billing.example.com/invoices >> /var/log/mlola-invoice.log 2>&1

name: invoice
on:
  schedule: [{ cron: "0 8 1 * *" }]
  workflow_dispatch:

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npx playwright install --with-deps chromium
      - name: Run the task
        env:
          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
        run: |
          npx @mlola/browser-cli browser run \
            --task task.json \
            --browser chromium --headless --no-human --yes --json | tee result.json
      - uses: actions/upload-artifact@v4
        with:
          name: invoice
          path: ~/.mlola/browser-runtime/runs/*/artifacts/**

{
  "defaults": { "upload": "allow", "send_message": "deny", "purchase": "takeover" },
  "restrictNavigation": true,
  "allowedOrigins": ["https://billing.example.com", "https://portal.example.com"],
  "secretsRequireTakeover": true
}

mlola browser run --policy policy.json --task task.json --stop-before "submit,pay"

import { BrowserAgent } from "@mlola/browser-runtime";

const agent = new BrowserAgent({ decision: "typesafe" });

agent.on("artifact-created", (event) => console.log("artifact:", event.payload.artifact.name));
agent.on("takeover-required", (event) => console.log("needs a person:", event.payload.prompt));
agent.on("fallback", (event) => console.log("escalated to", event.payload.to));

const run = await agent.run({
  goal: "Download my latest invoice",
  startUrl: "https://billing.example.com/invoices",
  successCriteria: { criteria: { kind: "artifact", documentType: "invoice" } },
});

console.log(run.status, run.verification?.status, run.artifacts);

mlola browser daemon start --port 7717
mlola browser daemon status
mlola browser daemon stop

npx mlola-browserd --port 7717        # foreground, when the daemon package is installed

TOKEN=$(cat ~/.mlola/browser-runtime/daemon/token)
curl -s -H "Authorization: Bearer $TOKEN" localhost:7717/v1/health
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"goal":"Download my latest invoice","startUrl":"https://billing.example.com/invoices"}' \
  localhost:7717/v1/runs
curl -s -H "Authorization: Bearer $TOKEN" "localhost:7717/v1/runs/<id>/events?since=0"

~/.mlola/browser-runtime/
  runs/<runId>/
    meta.json        goal, backend, start time
    events.jsonl     append-only event log (source of truth)
    summary.json     final result
    artifacts/       downloads + registry.json
    screenshots/     only per the screenshot policy
  daemon/            token, state, pid

MLOLA_HOME=/path/other   # override the runtime home

mlola browser sessions                    # daftar run terakhir
mlola browser sessions show r_abc12345     # ringkasan + metrik
mlola browser trace show r_abc12345 --limit 40
mlola browser trace show r_abc12345 --type RECOVERY
mlola browser trace summary r_abc12345     # JSON metrik

mlola browser eval --suite core        # acceptance suite, fast
mlola browser eval --suite security    # injection traps, secrets, destructive actions
mlola browser eval --suite matrix      # seeded DOM variations
mlola browser eval --suite stress      # large pages, re-render, slow downloads
mlola browser eval --suite all

npx @mlola/browser-evals run --suite core --provider typesafe   # the real fast path