Oya Browser README

Everyone else drives Chrome from the outside. We built the browser.

The automation lives inside it, not attached over the debugging protocol, so your agents stop
looking like a harness. Sign in once and every browser you start is already signed in.
Do the task once and Oya replays it forever, with no model in the loop.

Join the Discord · Talk to the founders

Start

npm i @oya-ai/browser

import { Oya } from "@oya-ai/browser";

const browser = await new Oya().browser.start();     // real Chrome, yours for the session
await browser.goto("https://news.ycombinator.com");
console.log(await browser.ask("What are the top 3 stories?"));
await browser.stop();

DONE: The top 3 stories on Hacker News are:
1. Google's Open Agentic Orchestrator
2. Samsung is expected to more than double output of its HBM4 and HBM4E DRAM
3. What happened to the Snowden archive

Set OYA_API_KEY from oyabrowser.com, or let your agent sign itself up (below). Node 20+.

No provider set up yet? Open the desktop browser on the same key and start() hands that one over, so those five lines work with nothing else configured. npx @oya-ai/cli init picks where browsers run when you want it to start them.

For AI agents

Are you an AI agent (OpenClaw, Hermes, Claude Code, Codex, Cursor or any other) looking for a browser? Everything below works with no person at a dashboard. Full reference, written for you: oyabrowser.com/llms.txt.

As a skill, for any agent that reads SKILL.md:

npx skills add OyadotAI/oya-browser

In code (Node 22.3+). Sign yourself up with your person's email, then use their own browser, already signed in to their sites:

import { Oya } from "@oya-ai/browser";

await Oya.signup({ email: "person@example.com" });   // your own key, saved to ~/.oya/config.json
const browser = await new Oya().desktop.connect();   // pairs the Oya desktop app, imports their logins
await browser.goto("https://example.com");
const { markdown, elements } = await browser.analyze();

desktop.connect() asks your person to install the desktop app if it is missing, and to click Connect when it opens.

Over MCP, for tools that cannot run code (Claude Desktop, Cursor, Windsurf and the rest): https://oyabrowser.com/mcp/pool with Authorization: Bearer <key>. In Claude Code:

claude mcp add --transport http oya https://oyabrowser.com/mcp/pool \
  --header "Authorization: Bearer $OYA_API_KEY"

Then just ask: "Start a browser, open Hacker News and summarise the top 3 stories." Oya is in the MCP registry as io.github.OyadotAI/oya-browser, on Smithery and on ClawHub as oya-browser.

Record it once, replay it forever

ask() costs a model call every time. Save the run and it never costs one again.

await browser.ask("Log in with {{user}} and {{pass}}. Open New Request for {{name}}.",
  { data: { name: "Alex Example" }, secrets: { user, pass } });
await browser.toPlaybook("new-request");             // the steps it just took

await replay.play("new-request", { name: "Sam Example", user, pass });   // no model, new inputs

Nine of ten public sites replay every recorded step with no model and no repair. The tenth is named, with its error. When a page really has changed, the agent finishes the run and its fix replaces the broken steps, so the next replay runs clean. A replay that meets a login signs in with the profile's saved credentials and carries on.

Values you gave in the prompt become variables. A free-text field the agent wrote itself, a comment or the answer to a question, is written fresh by your model on every replay instead of repeating the first run's words. Every playbook is also a Playwright module you can read and keep:

export default async function run(page, vars = {}, oya) {
  await page.getByLabel("Customer name:").first().fill(`${vars["custname"]}`);
  await page.getByLabel("Delivery instructions:").first().fill(vars["comments"] ?? (await oya.llm.answer("Delivery instructions:", vars)));
}

Move one to another environment with oya.playbooks.export(name) and oya.playbooks.import(doc), oya playbooks export|import on the command line, or Export and Import in the dashboard.

Sign in once

Scripted logins break on Google SSO, Okta, passkeys and Cloudflare. Don't script them. Import the logins you already have from Chrome, Arc, Brave, Edge or Firefox when you connect the desktop app, or sign in by hand once in it. Every browser you start on that persona is then already signed in: the session travels as cookies and localStorage, sealed at rest, because half the portals worth automating keep you signed in with neither one alone. Every way in and out.

For the portals that end the session server-side anyway, store the login and Oya signs in itself, and stops rather than retrying a password the site has already refused, because that is how a real account gets locked out.

Why it isn't flagged as a bot

Everyone else ships an SDK that drives headless Chrome over the debugging protocol. That is the easy way, and it is the shape anti-bot vendors have learned to look for. Oya is a real headful browser a person can sit in front of, and the automation runs inside the process:

• The persona's platform, timezone, locale, cores and screen are set through Chrome's own emulation before the first document, and again in workers and cross-site iframes. A value Chrome reports about itself cannot be caught lying.
• Reading a page uses an isolated world, so it needs no Runtime.enable, which is a known detection vector. Replay never turns it on.
• Console and network come from browser-process APIs, not the Log and Network domains, so watching a run adds nothing a page can see.

Measured, not asserted: 0% CreepJS headless score (bare headless Chrome: 100%) and 31 of 31 Bot.Sannysoft, re-run on 2026-09-20. Nobody can promise you are never detected (our own numbers page says so), but you can run the harness yourself and see what it says.

Self-host

curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh

It checks for git, Docker and Node 20+, asks six questions, then clones, writes the config, builds and waits for /readyz. Storage is SQLite (the default), Postgres or JSON files; browsers run on Docker, Kubernetes or your own machines. For production, deployments/ deploys the control plane and its browsers to one Docker host, Amazon ECS on Fargate, any Kubernetes cluster, or GKE Autopilot, with one deploy.sh each.

Self-hosting is free up to 5 cloud browsers running at once. Past that, or if you are using it seriously, write to sales@getoya.ai for a license key (OYA_LICENSE_KEY). A self-hosted server sends Oya one anonymous ping a day (a random install id, the version and browser counts, nothing about your users or pages); see telemetry.

_{The browser itself, filmed in real time: a task asked in the Ask pane, the answer, and the run kept as a playbook. The green boxes are the page as the agent reads it: every element it can act on, numbered. The four-minute version goes on to LinkedIn already signed in, Amazon, and a login it completes by itself (subtitles included).}

The rest

Packages

npm test                 # server, CLI and packages; ui and browser run their own (see AGENTS.md)
cd server && npm run stealth -- --live   # the stealth numbers, on your machine

License

The SDK and CLI are MIT. Embed them in commercial agents. Everything else is source-available under the Sustainable Use License: free for internal business use, research and non-commercial use, self-hosted up to 5 cloud browsers at once. Beyond that, write to sales@getoya.ai.