Smithery is now a part of Arcade.dev! Read more in our announcement here
Drive real Chrome browsers through 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.
Prefer 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 "Also import my logins" ticked (on macOS, allow "Chrome Safe Storage"). 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.
start_browser, starts a browser and makes every other tool drive it. Optional: persona ("auto", "default" or an id), provider, url.navigate(url), then analyze_page().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_playbooks and run_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.
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.
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).
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.
scroll("down", 800) returns a fresh analysis.screenshot, then click_coordinates(x, y). Hover with mouse_move to reveal menus."auto" picks the least recently used persona under its concurrency cap; "default" is the key's own.oya personas clone <id>).captcha: "auto" (SDK) solves CAPTCHAs as they appear; browser.solveCaptcha() solves one on demand. Over MCP: solve_captcha.sign_in fills a login form with the persona's stored credentials for the site and complete_mfa enters 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 a liveViewUrl, a person has to approve (push, passkey): give the user that URL and wait.oya takeover <id>, the human works in oya open --id <id>, then oya release <id> and oya resume <id>.navigate once, then wait for a selector or take a screenshot.Docs: https://oyabrowser.com/docs · For agents: https://oyabrowser.com/llms.txt
