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.
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
Markdown
[](/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
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.
- {
- "name": "oya",
- "description": "Oya's plugins for Claude Code: real Chrome browsers your agent can start, read and drive.",
- "owner": {
- "name": "Oya",
- "url": "https://getoya.ai"
- },
- "plugins": [
- {
- "name": "oya-browser",
- "source": "./",
- "description": "Real Chrome browsers for your agent: the Oya MCP server (start_browser, analyze_page, click, type…) plus a skill that teaches the workflow.",
- "homepage": "https://oyabrowser.com",
- "repository": "https://github.com/OyadotAI/oya-browser",
- "keywords": [
- "browser",
- "automation",
- "mcp",
- "chrome",
- "scraping",
- "captcha",
- "ai-agent",
- "browser-agent",
- "agent-skills",
- "sdk",
- "logins"
- ],
- "category": "automation"
- }
- ]
- }
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.
- <p align="center">
- <img src="assets/oya-banner.svg" alt="Oya Browser" width="100%">
- </p>
- <p align="center">
- <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>
- <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>
- <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>
- <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-Sustainable_Use_%2B_MIT_SDK-157a13" alt="License"></a>
- <a href="https://discord.gg/wqSeXJPygn"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
- <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>
- </p>
- # Oya Browser
- Oya Browser is a HIPAA-compliant browser for healthcare and regulated work: an AI browser on your
- desktop, and an agentic browser your agents run in the cloud or self-hosted, with every action on a
- tamper-evident audit trail. An agent completes a task once in natural language; Oya records the
- steps as a playbook that replays deterministically, without calling a model, and repairs individual
- steps when a page changes. People can watch any session and take control at any time.
- This repository contains the community edition: the browser, the control plane, the web console,
- the TypeScript SDK and the CLI. HIPAA compliance and a signed BAA come with Oya Cloud and the
- enterprise edition.
- - [Features](#features)
- - [Requirements](#requirements)
- - [Quickstart](#quickstart)
- - [Usage](#usage)
- - [Samples](#samples)
- - [Deployment](#deployment)
- - [Security and compliance](#security-and-compliance)
- - [Documentation](#documentation)
- - [Support](#support)
- - [Contributing](#contributing)
- - [License](#license)
- ## Features
- - **Record and replay.** A successful `ask()` is saved with `toPlaybook()` and replayed with
- `play()` using new inputs and no model calls. Each playbook is also exported as a Playwright
- module. In a [ten-site benchmark](docs/replay-benchmark.md), nine sites replayed every recorded
- step with healing disabled.
- - **Step repair.** When a recorded step no longer matches the page, the agent completes that step
- and the playbook is updated. Repair can be disabled per call.
- - **Stable browser identity.** Personas bind a fingerprint, cookie store and proxy that persist
- across sessions ([stealth results](docs/stealth.md): 0% headless on CreepJS, 31/31 on
- Sannysoft).
- - **Authentication.** Stored passwords and TOTP seeds are sealed and never exposed to the model.
- CAPTCHA detection and solving, and reuse of logins from your desktop browser, are built in
- ([logins](docs/logins.md)).
- - **Human in the loop.** Any session can be watched live and taken over, then returned to the
- agent.
- - **Provider choice.** The same API runs browsers on your own Docker hosts, Oya Cloud,
- Browserbase, Steel, Anchor, Browser Use or any Chrome endpoint ([comparison](docs/why-oya.md)).
- - **Standard protocols.** Every browser exposes CDP for Playwright, Puppeteer and similar
- clients, and an MCP endpoint for AI assistants.
- <p align="center">
- <img src="assets/prior-auth.gif" alt="An agent completes a prior authorization in a mock payer portal" width="100%">
- </p>
- <p align="center"><sub>An agent session in the Oya desktop app, accelerated. The portal and patient data are fictional.</sub></p>
- ## Requirements
- | Component | Version |
- | :--- | :--- |
- | Node.js | 20 or later |
- | Docker | Docker Desktop or Docker Engine with buildx for all deployment examples; Compose 2.24 or later for Docker deployments |
- | Deployment tools | `kubectl` + `python3` for Kubernetes; AWS CLI v2 for ECS; `gcloud`, `kubectl`, `python3` and `gke-gcloud-auth-plugin` for GKE |
- | Model API key | Anthropic, OpenAI or Gemini, for natural-language tasks |
- ## Quickstart
- This quickstart installs the control plane and one browser on your machine with Docker, then runs
- a sample that records a task and replays it.
- ### 1. Install the control plane
- Export a model API key, then run the installer:
- ```bash
- export ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY, or GEMINI_API_KEY
- curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh -s -- --yes
- ```
- The installer clones this repository to `~/oya-browser`, starts the services and prints the
- connection settings. Export them:
- ```bash
- export OYA_BASE_URL=http://localhost:3100
- export OYA_API_KEY=oya_...
- ```
- ### 2. Install the SDK
- ```bash
- npm install @oya-ai/browser
- ```
- ### 3. Run the sample
- Save the following as `agent.mjs` and run `node agent.mjs`:
- ```js
- import { Oya } from '@oya-ai/browser';
- const browser = await new Oya().browser.start();
- await browser.goto('https://httpbin.org/forms/post');
- // Run 1: the agent works it out, and Oya records what it did.
- let t = Date.now();
- await browser.ask('Order a large pizza for {{name}}, then submit the order', { data: { name: 'Ada' } });
- await browser.toPlaybook('pizza');
- console.log(`agent: ${(Date.now() - t) / 1000}s`);
- // Every run after: the recorded steps with new inputs. No LLM in the loop.
- t = Date.now();
- await browser.play('pizza', { name: 'Alan' });
- console.log(`replay: ${(Date.now() - t) / 1000}s, no model`);
- await browser.stop();
- ```
- The agent completes the order once and the result is saved as the playbook `pizza`. The replay
- submits the same order for a different name without calling the model. Output from one run with
- Gemini 3.8 Flash:
- ```text
- agent: 152.712s
- replay: 14.246s, no model
- ```
- Agent time depends on the model; replay time does not. To watch the session, open
- http://localhost:3100 and sign in with the same API key.
- ### Using Oya Cloud instead
- To skip the local installation, create an API key at [oyabrowser.com](https://oyabrowser.com),
- export only `OYA_API_KEY`, and run the same sample. `start()` uses the
- [Oya desktop app](https://oyabrowser.com/#download) when it is open and signed in, and otherwise
- starts a browser in Oya Cloud.
- ## Usage
- ### Choosing a model
- By default, `ask()` uses the model configured for your API key. To choose one in code, pass
- `model` to the client. The setting applies to that client only and is not saved:
- ```js
- const oya = new Oya({
- model: { provider: 'anthropic', name: 'claude-sonnet-5', apiKey: process.env.ANTHROPIC_API_KEY },
- });
- ```
- Supported providers are `openai`, `anthropic`, `gemini`, `vertex` and `openrouter`. When
- `apiKey` is set, requests go directly to that provider and are billed to your account.
- ### Connecting Playwright and other CDP clients
- Every Oya browser exposes a CDP endpoint, so Playwright, Puppeteer, Stagehand and browser-use
- connect without changes:
- ```js
- import { chromium } from 'playwright-core';
- import { Oya } from '@oya-ai/browser';
- const browser = await new Oya().browser.start();
- const cdp = await chromium.connectOverCDP(browser.cdpUrl);
- const context = cdp.contexts()[0];
- const page = context.pages()[0] ?? (await context.newPage());
- await page.goto('https://example.com');
- console.log(await page.title());
- await cdp.close();
- await browser.stop();
- ```
- ### Connecting AI assistants
- Install the [desktop app](https://oyabrowser.com/#download), open it and click
- Connect next to your agent (Claude Code, Codex, Cursor, VS Code and others appear
- when installed). That adds an MCP server named `oya-browser` at
- `http://127.0.0.1:47321/mcp` to the agent's config; no account, no key. The agent
- then uses Oya as its browser in place of Chrome: each session gets its own tab,
- you keep yours, and you can take control at any time.
- With no desktop (servers, containers, CI), any MCP client can use Oya Cloud. For
- Claude Code:
- ```bash
- claude mcp add --transport http oya https://oyabrowser.com/mcp/pool \
- --header "Authorization: Bearer $OYA_API_KEY"
- ```
- Setup instructions written for agents are published at
- [oyabrowser.com/llms.txt](https://oyabrowser.com/llms.txt).
- ## Samples
- The [`examples`](examples/README.md) directory contains runnable TypeScript samples. After the
- quickstart, the installer's copy is ready to use:
- ```bash
- cd ~/oya-browser/examples && npm install
- cp .env.example .env # set OYA_BASE_URL and OYA_API_KEY
- npx tsx --env-file=.env playwright/01-connect.ts
- ```
- | Sample | Description | Runs on |
- | :--- | :--- | :--- |
- | [`sdk/01-quickstart.ts`](examples/sdk/01-quickstart.ts) | Start a browser and complete a task in natural language | Local installation or Oya Cloud |
- | [`sdk/05-playbooks.ts`](examples/sdk/05-playbooks.ts) | Record, replay, background runs and step repair | Local installation or Oya Cloud |
- | [`playwright/01-connect.ts`](examples/playwright/01-connect.ts) | Playwright through the CDP endpoint | Local installation or Oya Cloud |
- | [`sdk/03-mfa.ts`](examples/sdk/03-mfa.ts) | Password and TOTP sign-in with sealed credentials | Desktop app |
- | [`sdk/02-captcha.ts`](examples/sdk/02-captcha.ts) | CAPTCHA detection and solving | Oya Cloud, or a configured solver |
- | [`sdk/04-personas.ts`](examples/sdk/04-personas.ts) | Persistent browser identities | Oya Cloud |
- | [`playwright/reddit/`](examples/playwright/reddit/) | Ten parallel browsers through a residential proxy | Oya Cloud, with a proxy assigned to the persona |
- | [`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 |
- The local installation runs one Docker browser. For samples that require Oya Cloud, use an API
- key from [oyabrowser.com](https://oyabrowser.com) and leave `OYA_BASE_URL` unset.
- ## Deployment
- The quickstart above uses `--yes` for SQLite and one Docker browser. For a guided deployment,
- run the installer without `--yes`:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh
- ```
- Choose **Docker**, **Kubernetes**, **Amazon ECS** or **Google Cloud / GKE**. The wizard uses the
- existing [`deployments/`](deployments/README.md) examples to deploy the control plane, Postgres
- and browser runtime together. Advanced settings cover image overrides, networking, replicas
- and optional services. Each question explains the value, its format and default, and where to
- find it with a lookup command or console path. Lookup commands are shown for you to run.
- The flow moves through Target, Configure, Deploy and Verify, checks prerequisites, waits for
- readiness, then verifies a browser session before reporting success.
- From a checkout, run the current local wizard:
- ```bash
- make wizard
- make wizard ARGS="--target k8s" # skip the destination menu
- make wizard ARGS="--target docker --dry-run" # preview without changing files or resources
- ```
- Nonsecret answers are saved to `oya-install.json`; `oya install --config oya-install.json`
- repeats that deployment without questions. Existing version 1 plans and bare `--yes` keep the
- original quickstart behavior. Kubernetes and GKE smoke checks use a private port-forward;
- public DNS and TLS may need additional setup. Cloud resources are billable.
- See the [self-hosting guide](docs/self-hosting.md) for saved plans, credentials and recovery,
- and the [deployment guides](deployments/README.md) for prerequisites, backups and removal.
- ## Security and compliance
- Self-hosted deployments include host-level egress rules and a tamper-evident audit trail. See the
- [control evidence](compliance/EVIDENCE.md) and the [trust center](https://oyabrowser.com/trust).
- To report a vulnerability, follow [SECURITY.md](SECURITY.md).
- An enterprise edition, including a HIPAA-ready offering, is maintained separately. Contact
- [sales@getoya.ai](mailto:sales@getoya.ai).
- ## Documentation
- | Topic | Link |
- | :--- | :--- |
- | SDK reference | [packages/sdk](packages/sdk/README.md) |
- | CLI reference | [packages/cli](packages/cli/README.md) |
- | Self-hosting | [docs/self-hosting.md](docs/self-hosting.md) |
- | Logins and sessions | [docs/logins.md](docs/logins.md) |
- | Replay benchmark | [docs/replay-benchmark.md](docs/replay-benchmark.md) |
- | Architecture | [ARCHITECTURE.md](ARCHITECTURE.md) |
- ## Support
- - Questions and discussion: [Discord](https://discord.gg/wqSeXJPygn)
- - Bug reports and feature requests: [GitHub Issues](https://github.com/OyadotAI/oya-browser/issues)
- - Commercial licensing and enterprise: [sales@getoya.ai](mailto:sales@getoya.ai)
- ## Contributing
- Contributions are welcome. To set up a development environment:
- ```bash
- git clone https://github.com/OyadotAI/oya-browser.git && cd oya-browser
- npm run setup
- ```
- Read [ARCHITECTURE.md](ARCHITECTURE.md) for an overview of the codebase and [AGENTS.md](AGENTS.md)
- for conventions and the checks each part requires.
- | Path | Contents |
- | :--- | :--- |
- | [`packages/sdk`](packages/sdk) | `@oya-ai/browser`, the TypeScript SDK (MIT) |
- | [`packages/cli`](packages/cli) | `@oya-ai/cli`, installation and command-line tools (MIT) |
- | [`browser`](browser) | The desktop browser and the cloud browser image |
- | [`server`](server) | API, MCP, browser connections and control plane |
- | [`ui`](ui) | Web console and public site |
- ## License
- The SDK and CLI are licensed under MIT. All other components are available under the Sustainable
- Use License. See [LICENSE.md](LICENSE.md) for permitted use, self-hosting terms and commercial
- licensing.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.