The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Oya Browser listing page.
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
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.
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:
In code (Node 22.3+). Sign yourself up with your person's email, then use their own browser, already signed in to their sites:
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:
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.
ask() costs a model call every time. Save the run and it never costs one again.
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:
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.
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.
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:
Runtime.enable, which is a known detection
vector. Replay never turns it on.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.
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).
| CAPTCHA and 2FA | Solved where they can be, handed to a person where they can't |
| Record it yourself | The desktop recorder keeps a draft you edit step by step, validate in fresh tabs and save as a playbook (how) |
| Routines | Saved prompts the desktop agent runs every N minutes or daily at a set time, with each run's steps and answer kept |
| It proves what it did | A hash-chained audit trail the database won't let you rewrite, host allow-listing, regenerable evidence |
| It isn't one vendor | Oya Cloud, Browserbase, Steel, Anchor, Browser Use or your own Chrome (why) |
| It keeps your tools | Every browser has a cdpUrl, so Playwright and Puppeteer connect unchanged |
| Full docs | SDK · CLI · self-hosting · deployments · moving logins · examples · oyabrowser.com/docs · for agents |
| Package | |
|---|---|
@oya-ai/browser | TypeScript SDK. ESM and CJS, typed, zero runtime dependencies. |
@oya-ai/cli | The fleet, the live view, the installer. |
server · ui · browser | Control plane, console, and the browser itself. |
skills/oya-browser | The agent skill: npx skills add OyadotAI/oya-browser. |
deployments | Production deploys: Docker, ECS, Kubernetes, GKE. |
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.