Skip to content
Back to search

oya-browser

The browser control plane for AI agents. One API over Oya Cloud, Browserbase, Steel, Anchor, Browser Use and your own Chrome, with persistent personas, CAPTCHA and MFA handling, and live human takeover.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/OyadotAI/oya-browser with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/OyadotAI/oya-browser'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oyadotai--oya-browser/badge.svg)](/listings/oyadotai--oya-browser)

HTML

<a href="/listings/oyadotai--oya-browser"><img src="/api/listings/oyadotai--oya-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "oya",
  3. "description": "Oya's plugins for Claude Code: real Chrome browsers your agent can start, read and drive.",
  4. "owner": {
  5. "name": "Oya",
  6. "url": "https://getoya.ai"
  7. },
  8. "plugins": [
  9. {
  10. "name": "oya-browser",
  11. "source": "./",
  12. "description": "Real Chrome browsers for your agent: the Oya MCP server (start_browser, analyze_page, click, type…) plus a skill that teaches the workflow.",
  13. "homepage": "https://oyabrowser.com",
  14. "repository": "https://github.com/OyadotAI/oya-browser",
  15. "keywords": [
  16. "browser",
  17. "automation",
  18. "mcp",
  19. "chrome",
  20. "scraping",
  21. "captcha",
  22. "ai-agent",
  23. "browser-agent",
  24. "agent-skills",
  25. "sdk",
  26. "logins"
  27. ],
  28. "category": "automation"
  29. }
  30. ]
  31. }
README.md · README · 306 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/oya-banner.svg" alt="Oya Browser" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/OyadotAI/oya-browser/releases/latest"><img src="https://badgen.net/github/tag/OyadotAI/oya-browser?label=release&color=39ed35" alt="Latest release"></a>
  6. <a href="https://www.npmjs.com/package/@oya-ai/browser"><img src="https://badgen.net/npm/v/@oya-ai/browser?label=@oya-ai/browser&color=39ed35" alt="npm: @oya-ai/browser"></a>
  7. <a href="https://codecov.io/gh/OyadotAI/oya-browser"><img src="https://badgen.net/codecov/c/github/OyadotAI/oya-browser?label=coverage" alt="Coverage"></a>
  8. <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-Sustainable_Use_%2B_MIT_SDK-157a13" alt="License"></a>
  9. <a href="https://discord.gg/wqSeXJPygn"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  10. <a href="https://mcptry.com/servers/io.github.OyadotAI/oya-browser"><img src="https://mcptry.com/badge/io.github.OyadotAI/oya-browser" alt="mcptry: live status and score"></a>
  11. </p>
  12. # Oya Browser
  13. Oya Browser is a HIPAA-compliant browser for healthcare and regulated work: an AI browser on your
  14. desktop, and an agentic browser your agents run in the cloud or self-hosted, with every action on a
  15. tamper-evident audit trail. An agent completes a task once in natural language; Oya records the
  16. steps as a playbook that replays deterministically, without calling a model, and repairs individual
  17. steps when a page changes. People can watch any session and take control at any time.
  18. This repository contains the community edition: the browser, the control plane, the web console,
  19. the TypeScript SDK and the CLI. HIPAA compliance and a signed BAA come with Oya Cloud and the
  20. enterprise edition.
  21. - [Features](#features)
  22. - [Requirements](#requirements)
  23. - [Quickstart](#quickstart)
  24. - [Usage](#usage)
  25. - [Samples](#samples)
  26. - [Deployment](#deployment)
  27. - [Security and compliance](#security-and-compliance)
  28. - [Documentation](#documentation)
  29. - [Support](#support)
  30. - [Contributing](#contributing)
  31. - [License](#license)
  32. ## Features
  33. - **Record and replay.** A successful `ask()` is saved with `toPlaybook()` and replayed with
  34. `play()` using new inputs and no model calls. Each playbook is also exported as a Playwright
  35. module. In a [ten-site benchmark](docs/replay-benchmark.md), nine sites replayed every recorded
  36. step with healing disabled.
  37. - **Step repair.** When a recorded step no longer matches the page, the agent completes that step
  38. and the playbook is updated. Repair can be disabled per call.
  39. - **Stable browser identity.** Personas bind a fingerprint, cookie store and proxy that persist
  40. across sessions ([stealth results](docs/stealth.md): 0% headless on CreepJS, 31/31 on
  41. Sannysoft).
  42. - **Authentication.** Stored passwords and TOTP seeds are sealed and never exposed to the model.
  43. CAPTCHA detection and solving, and reuse of logins from your desktop browser, are built in
  44. ([logins](docs/logins.md)).
  45. - **Human in the loop.** Any session can be watched live and taken over, then returned to the
  46. agent.
  47. - **Provider choice.** The same API runs browsers on your own Docker hosts, Oya Cloud,
  48. Browserbase, Steel, Anchor, Browser Use or any Chrome endpoint ([comparison](docs/why-oya.md)).
  49. - **Standard protocols.** Every browser exposes CDP for Playwright, Puppeteer and similar
  50. clients, and an MCP endpoint for AI assistants.
  51. <p align="center">
  52. <img src="assets/prior-auth.gif" alt="An agent completes a prior authorization in a mock payer portal" width="100%">
  53. </p>
  54. <p align="center"><sub>An agent session in the Oya desktop app, accelerated. The portal and patient data are fictional.</sub></p>
  55. ## Requirements
  56. | Component | Version |
  57. | :--- | :--- |
  58. | Node.js | 20 or later |
  59. | Docker | Docker Desktop or Docker Engine with buildx for all deployment examples; Compose 2.24 or later for Docker deployments |
  60. | Deployment tools | `kubectl` + `python3` for Kubernetes; AWS CLI v2 for ECS; `gcloud`, `kubectl`, `python3` and `gke-gcloud-auth-plugin` for GKE |
  61. | Model API key | Anthropic, OpenAI or Gemini, for natural-language tasks |
  62. ## Quickstart
  63. This quickstart installs the control plane and one browser on your machine with Docker, then runs
  64. a sample that records a task and replays it.
  65. ### 1. Install the control plane
  66. Export a model API key, then run the installer:
  67. ```bash
  68. export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY, or GEMINI_API_KEY
  69. curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh -s -- --yes
  70. ```
  71. The installer clones this repository to `~/oya-browser`, starts the services and prints the
  72. connection settings. Export them:
  73. ```bash
  74. export OYA_BASE_URL=http://localhost:3100
  75. export OYA_API_KEY=oya_...
  76. ```
  77. ### 2. Install the SDK
  78. ```bash
  79. npm install @oya-ai/browser
  80. ```
  81. ### 3. Run the sample
  82. Save the following as `agent.mjs` and run `node agent.mjs`:
  83. ```js
  84. import { Oya } from '@oya-ai/browser';
  85. const browser = await new Oya().browser.start();
  86. await browser.goto('https://httpbin.org/forms/post');
  87. // Run 1: the agent works it out, and Oya records what it did.
  88. let t = Date.now();
  89. await browser.ask('Order a large pizza for {{name}}, then submit the order', { data: { name: 'Ada' } });
  90. await browser.toPlaybook('pizza');
  91. console.log(`agent: ${(Date.now() - t) / 1000}s`);
  92. // Every run after: the recorded steps with new inputs. No LLM in the loop.
  93. t = Date.now();
  94. await browser.play('pizza', { name: 'Alan' });
  95. console.log(`replay: ${(Date.now() - t) / 1000}s, no model`);
  96. await browser.stop();
  97. ```
  98. The agent completes the order once and the result is saved as the playbook `pizza`. The replay
  99. submits the same order for a different name without calling the model. Output from one run with
  100. Gemini 3.8 Flash:
  101. ```text
  102. agent: 152.712s
  103. replay: 14.246s, no model
  104. ```
  105. Agent time depends on the model; replay time does not. To watch the session, open
  106. http://localhost:3100 and sign in with the same API key.
  107. ### Using Oya Cloud instead
  108. To skip the local installation, create an API key at [oyabrowser.com](https://oyabrowser.com),
  109. export only `OYA_API_KEY`, and run the same sample. `start()` uses the
  110. [Oya desktop app](https://oyabrowser.com/#download) when it is open and signed in, and otherwise
  111. starts a browser in Oya Cloud.
  112. ## Usage
  113. ### Choosing a model
  114. By default, `ask()` uses the model configured for your API key. To choose one in code, pass
  115. `model` to the client. The setting applies to that client only and is not saved:
  116. ```js
  117. const oya = new Oya({
  118. model: { provider: 'anthropic', name: 'claude-sonnet-5', apiKey: process.env.ANTHROPIC_API_KEY },
  119. });
  120. ```
  121. Supported providers are `openai`, `anthropic`, `gemini`, `vertex` and `openrouter`. When
  122. `apiKey` is set, requests go directly to that provider and are billed to your account.
  123. ### Connecting Playwright and other CDP clients
  124. Every Oya browser exposes a CDP endpoint, so Playwright, Puppeteer, Stagehand and browser-use
  125. connect without changes:
  126. ```js
  127. import { chromium } from 'playwright-core';
  128. import { Oya } from '@oya-ai/browser';
  129. const browser = await new Oya().browser.start();
  130. const cdp = await chromium.connectOverCDP(browser.cdpUrl);
  131. const context = cdp.contexts()[0];
  132. const page = context.pages()[0] ?? (await context.newPage());
  133. await page.goto('https://example.com');
  134. console.log(await page.title());
  135. await cdp.close();
  136. await browser.stop();
  137. ```
  138. ### Connecting AI assistants
  139. Install the [desktop app](https://oyabrowser.com/#download), open it and click
  140. Connect next to your agent (Claude Code, Codex, Cursor, VS Code and others appear
  141. when installed). That adds an MCP server named `oya-browser` at
  142. `http://127.0.0.1:47321/mcp` to the agent's config; no account, no key. The agent
  143. then uses Oya as its browser in place of Chrome: each session gets its own tab,
  144. you keep yours, and you can take control at any time.
  145. With no desktop (servers, containers, CI), any MCP client can use Oya Cloud. For
  146. Claude Code:
  147. ```bash
  148. claude mcp add --transport http oya https://oyabrowser.com/mcp/pool \
  149. --header "Authorization: Bearer $OYA_API_KEY"
  150. ```
  151. Setup instructions written for agents are published at
  152. [oyabrowser.com/llms.txt](https://oyabrowser.com/llms.txt).
  153. ## Samples
  154. The [`examples`](examples/README.md) directory contains runnable TypeScript samples. After the
  155. quickstart, the installer's copy is ready to use:
  156. ```bash
  157. cd ~/oya-browser/examples && npm install
  158. cp .env.example .env # set OYA_BASE_URL and OYA_API_KEY
  159. npx tsx --env-file=.env playwright/01-connect.ts
  160. ```
  161. | Sample | Description | Runs on |
  162. | :--- | :--- | :--- |
  163. | [`sdk/01-quickstart.ts`](examples/sdk/01-quickstart.ts) | Start a browser and complete a task in natural language | Local installation or Oya Cloud |
  164. | [`sdk/05-playbooks.ts`](examples/sdk/05-playbooks.ts) | Record, replay, background runs and step repair | Local installation or Oya Cloud |
  165. | [`playwright/01-connect.ts`](examples/playwright/01-connect.ts) | Playwright through the CDP endpoint | Local installation or Oya Cloud |
  166. | [`sdk/03-mfa.ts`](examples/sdk/03-mfa.ts) | Password and TOTP sign-in with sealed credentials | Desktop app |
  167. | [`sdk/02-captcha.ts`](examples/sdk/02-captcha.ts) | CAPTCHA detection and solving | Oya Cloud, or a configured solver |
  168. | [`sdk/04-personas.ts`](examples/sdk/04-personas.ts) | Persistent browser identities | Oya Cloud |
  169. | [`playwright/reddit/`](examples/playwright/reddit/) | Ten parallel browsers through a residential proxy | Oya Cloud, with a proxy assigned to the persona |
  170. | [`multi-vendor/`](examples/multi-vendor/01-multi-vendor.ts) | One script across Oya Cloud, Browserbase, Steel, Anchor and Browser Use | Oya Cloud and each provider's API key |
  171. The local installation runs one Docker browser. For samples that require Oya Cloud, use an API
  172. key from [oyabrowser.com](https://oyabrowser.com) and leave `OYA_BASE_URL` unset.
  173. ## Deployment
  174. The quickstart above uses `--yes` for SQLite and one Docker browser. For a guided deployment,
  175. run the installer without `--yes`:
  176. ```bash
  177. curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh
  178. ```
  179. Choose **Docker**, **Kubernetes**, **Amazon ECS** or **Google Cloud / GKE**. The wizard uses the
  180. existing [`deployments/`](deployments/README.md) examples to deploy the control plane, Postgres
  181. and browser runtime together. Advanced settings cover image overrides, networking, replicas
  182. and optional services. Each question explains the value, its format and default, and where to
  183. find it with a lookup command or console path. Lookup commands are shown for you to run.
  184. The flow moves through Target, Configure, Deploy and Verify, checks prerequisites, waits for
  185. readiness, then verifies a browser session before reporting success.
  186. From a checkout, run the current local wizard:
  187. ```bash
  188. make wizard
  189. make wizard ARGS="--target k8s" # skip the destination menu
  190. make wizard ARGS="--target docker --dry-run" # preview without changing files or resources
  191. ```
  192. Nonsecret answers are saved to `oya-install.json`; `oya install --config oya-install.json`
  193. repeats that deployment without questions. Existing version 1 plans and bare `--yes` keep the
  194. original quickstart behavior. Kubernetes and GKE smoke checks use a private port-forward;
  195. public DNS and TLS may need additional setup. Cloud resources are billable.
  196. See the [self-hosting guide](docs/self-hosting.md) for saved plans, credentials and recovery,
  197. and the [deployment guides](deployments/README.md) for prerequisites, backups and removal.
  198. ## Security and compliance
  199. Self-hosted deployments include host-level egress rules and a tamper-evident audit trail. See the
  200. [control evidence](compliance/EVIDENCE.md) and the [trust center](https://oyabrowser.com/trust).
  201. To report a vulnerability, follow [SECURITY.md](SECURITY.md).
  202. An enterprise edition, including a HIPAA-ready offering, is maintained separately. Contact
  203. [sales@getoya.ai](mailto:sales@getoya.ai).
  204. ## Documentation
  205. | Topic | Link |
  206. | :--- | :--- |
  207. | SDK reference | [packages/sdk](packages/sdk/README.md) |
  208. | CLI reference | [packages/cli](packages/cli/README.md) |
  209. | Self-hosting | [docs/self-hosting.md](docs/self-hosting.md) |
  210. | Logins and sessions | [docs/logins.md](docs/logins.md) |
  211. | Replay benchmark | [docs/replay-benchmark.md](docs/replay-benchmark.md) |
  212. | Architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
  213. ## Support
  214. - Questions and discussion: [Discord](https://discord.gg/wqSeXJPygn)
  215. - Bug reports and feature requests: [GitHub Issues](https://github.com/OyadotAI/oya-browser/issues)
  216. - Commercial licensing and enterprise: [sales@getoya.ai](mailto:sales@getoya.ai)
  217. ## Contributing
  218. Contributions are welcome. To set up a development environment:
  219. ```bash
  220. git clone https://github.com/OyadotAI/oya-browser.git && cd oya-browser
  221. npm run setup
  222. ```
  223. Read [ARCHITECTURE.md](ARCHITECTURE.md) for an overview of the codebase and [AGENTS.md](AGENTS.md)
  224. for conventions and the checks each part requires.
  225. | Path | Contents |
  226. | :--- | :--- |
  227. | [`packages/sdk`](packages/sdk) | `@oya-ai/browser`, the TypeScript SDK (MIT) |
  228. | [`packages/cli`](packages/cli) | `@oya-ai/cli`, installation and command-line tools (MIT) |
  229. | [`browser`](browser) | The desktop browser and the cloud browser image |
  230. | [`server`](server) | API, MCP, browser connections and control plane |
  231. | [`ui`](ui) | Web console and public site |
  232. ## License
  233. The SDK and CLI are licensed under MIT. All other components are available under the Sustainable
  234. Use License. See [LICENSE.md](LICENSE.md) for permitted use, self-hosting terms and commercial
  235. licensing.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.