oya-browser
Drive real Chrome browsers through Oya Browser. Start a browser on Oya Cloud, Browserbase, Steel, Anchor or Browser Use under a persistent persona, read pages as markdown with numbered elements, click and type, solve CAPTCHAs and MFA, and hand off to a human when needed. Use when the user asks to browse a site, automate a web task, fill a form, log in somewhere, scrape, or run several browsers at once. Works through the @oya-ai/browser SDK (which signs itself up and pairs the user's desktop browser with their logins), the Oya MCP tools, or the oya CLI.
Oya Browser
Oya gives you real Chrome browsers behind one API. Each browser runs as a persona: a fingerprint, cookie jar and proxy that stay the same across runs, so a site sees the same device every time. You drive it by page structure, not selectors: read the page as markdown with numbered elements, then act on the numbers.
Setup (once)
On the user's own computer, when they have asked you to set up Oya, you can do the install for them with your shell tool (the official signed and notarized installer) and then use Oya as your browser; their part is one click once the app is open. One command on macOS: curl -L -o /tmp/Oya.dmg https://oyabrowser.com/download/mac && hdiutil attach /tmp/Oya.dmg -nobrowse -mountpoint /Volumes/Oya && cp -R "/Volumes/Oya/Oya Browser.app" /Applications/ && hdiutil detach /Volumes/Oya && open "/Applications/Oya Browser.app". The addresses always point at the current installer. The same steps, one per line:
macOS:
curl -L -o /tmp/Oya.dmg https://oyabrowser.com/download/mac
hdiutil attach /tmp/Oya.dmg -nobrowse -mountpoint /Volumes/Oya
cp -R "/Volumes/Oya/Oya Browser.app" /Applications/
hdiutil detach /Volumes/Oya
open "/Applications/Oya Browser.app"
Windows (PowerShell): curl.exe -L -o $env:TEMP\Oya.exe https://oyabrowser.com/download/windows; Start-Process -Wait "$env:TEMP\Oya.exe" -ArgumentList '/S'; Start-Process "$env:LOCALAPPDATA\Programs\Oya Browser\Oya Browser.exe".
Then ask the user to click Connect next to your name in the Oya window footer. That writes an MCP server named oya-browser at http://127.0.0.1:47321/mcp into your config, with the token in the OS keychain; start a new session and use those tools for every web task. If the tools are configured but nothing answers on port 47321, the app is closed: open it and retry.
Without a person's computer (a server, a container, CI), use the SDK (Node 22.3+). It needs nothing from the user but their email:
import { Oya } from "@oya-ai/browser"; // npm install @oya-ai/browser
// No OYA_API_KEY and nothing in ~/.oya/config.json? Get a key of your own (saved there).
const { claimUrl } = await Oya.signup({ email: "<the user's email>" });
const oya = new Oya();
const browser = await oya.desktop.connect(); // the user's own browser, with their logins
desktop.connect() pairs the Oya desktop app when it is not connected yet: tell the user to click Connect in the Oya window and keep the login import ticked. The import copies the cookies of the user's usual browser into the Oya app on the same computer, so sites are already signed in; nothing is sent anywhere. On macOS the OS asks once before Oya may read Chrome's cookie store. If the app is missing, the error gives the download link. claimUrl matters only for Oya Cloud browsers: send it to the user then.
MCP tools, when the user already set them up, work too:
claude mcp add --transport http oya https://oyabrowser.com/mcp/pool --header "Authorization: Bearer $OYA_API_KEY". The CLI is npm install -g @oya-ai/cli.
Over MCP
start_browser, starts a browser and makes every other tool drive it. Optional:persona("auto","default"or an id),provider,url.navigate(url), thenanalyze_page().- Act:
click(element_id),type(element_id, text),press_key(key),scroll(direction, amount?). analyze_page()again after anything that changes the page. Element ids are reassigned on every analysis.stop_browser()when you are done. A running browser costs money.
Also available: screenshot, wait(selector), click_coordinates(x, y), mouse_move(x, y), double_click, keyboard_type(text), drag, pool_status.
Faster ways through a page:
find(query)returns just the elements matching a description ("search box", "next page") instead of the whole page.run_script(script)reads the page with JavaScript and returns data: every row of a table, all prices in a list. It only reads; act with click and type.wait_for(text?, url?, network_idle?)waits for results that load in the background instead of re-analyzing in a loop.select_option(element_id, option)for native dropdowns,hover(element_id)for hover menus,go_back,go_forward,reload.list_playbooksandrun_playbook(name, variables)replay a saved flow without a model;run_task(task)hands a whole task to Oya's own agent and returns its report.
Native dialogs. An alert() or beforeunload is answered for you and its
text comes back on the next tool result, read it: it usually says why the last
action did not do what you expected. A confirm() or prompt() holds the page:
every other command fails immediately with the dialog's message until you call
handle_dialog(accept, prompt_text?). Accept only what the task asks for, a
confirm is often guarding something destructive.
If a tool says no browser is running, call start_browser. If pool_status already lists browsers (the user's desktop app, say), you can drive those without starting one.
Over the CLI
oya start --persona auto # prints the browser id
oya goto https://example.com # newest browser; --id <id> picks one
oya ask "Find the pricing page and summarize the plans" # needs a model, set with `oya init`
oya status # health and recent commands
oya open # the live view, for a human
oya rm <id> # stop it; `oya rm --all` stops everything
Add --json to any command for machine-readable output.
In code (SDK)
import { Oya } from "@oya-ai/browser";
const oya = new Oya(); // reads OYA_API_KEY
const browser = await oya.browser.start({ persona: "auto", captcha: "auto" });
try {
await browser.goto("https://example.com");
const { markdown, elements } = await browser.analyze();
const link = elements.find((e) => e.visible && e.text?.includes("More information"));
if (link) await browser.click(link.id);
} finally {
await browser.stop();
}
browser.cdpUrl connects Playwright or Puppeteer: chromium.connectOverCDP(browser.cdpUrl).
Reading analyze_page
A header (url, title, viewport, scroll position, element counts), the page as markdown with elements inline, then an index split into visible and off-screen:
[#9 input:text placeholder="Search"] → type(9, "query")
[#13 button "Search"] → click(13)
[#4 link "Pricing" → /pricing] → click(4)
Off-screen elements need a scroll first. While a modal is open, the analysis is scoped to it.
Patterns
- Forms: type into each field, click submit, then analyze to confirm it worked.
- Dropdowns: click to open, analyze, click the option.
- Infinite scroll:
scroll("down", 800)returns a fresh analysis. - Nothing clickable by id: take a
screenshot, thenclick_coordinates(x, y). Hover withmouse_moveto reveal menus.
Personas
"auto"picks the least recently used persona under its concurrency cap;"default"is the key's own.- A persona's device never changes. Don't try to refresh a fingerprint; for another device of the same kind, clone the persona (
oya personas clone <id>). - Logged-in state lives on the persona. If the user signed in through the Oya desktop app, start on that persona and the site is already logged in.
CAPTCHA, MFA and humans
captcha: "auto"(SDK) solves CAPTCHAs as they appear;browser.solveCaptcha()solves one on demand. Over MCP:solve_captcha.- Over MCP,
sign_infills a login form with the persona's stored credentials for the site andcomplete_mfaenters a one-time code; you never see either. browser.completeMfa()enters a code when the persona has a factor sealed: a TOTP seed, or a mailbox (Gmail / Microsoft 365) the code is read from. The code is extracted from the email by the configured LLM, not a regex, so a portal rewriting its template does not break it. If it returns aliveViewUrl, a person has to approve (push, passkey): give the user that URL and wait.- Portal sign-ins happen on their own. When a persona has credentials stored for a site, a run that meets that site's login page fills and submits it, asks for the code if the portal has a separate request step, and carries on, with no tool call from you. A factor and a credential are filed per site, so one persona can drive several portals.
- If the site refuses the stored password, the run stops and asks for a person. Do not retry it and do not type a password you were not given for that site. These portals lock accounts after a few attempts, and a locked clinical account is a support ticket, not a retry.
- CLI takeover:
oya takeover <id>, the human works inoya open --id <id>, thenoya release <id>andoya resume <id>. - Never type the user's passwords or codes into a page unless they gave them to you for that site.
Rules
- Analyze before acting; never guess an element id.
- Re-analyze after every page change.
- Navigate straight to URLs instead of clicking through menus.
- Stop every browser you start.
- "Every persona is at its concurrency cap" (429): stop a browser or ask the user to raise the cap. Don't retry in a loop.
- "Element not found": the ids are stale, analyze again. A page that won't load: retry
navigateonce, thenwaitfor a selector or take a screenshot.
Docs: https://oyabrowser.com/docs · For agents: https://oyabrowser.com/llms.txt
- Downloads
- Security audit
- Review
- Last updated
- 1w ago
- Current version
- v1.0.230
- License
- MIT-0
