Oya, the HIPAA-compliant agentic browser, over MCP: browse, run playbooks, hand a tab to a person.
io.github.OyadotAI/oya-browser MCP Server
The io.github.OyadotAI/oya-browser MCP server provides a “Real Chrome for agents” workflow. It can start a browser, read web pages as numbered markdown, and perform basic interactions such as clicking and typing, including handing off control to other steps.
🛠️ Key Features
Start a browser for agent use
Read pages as numbered markdown
Click on page elements
Type input into fields
Hand off to subsequent handling
🚀 Use Cases
Extract and navigate through web content with agent-driven browsing
Perform interactive steps on pages (clicking and typing)
Convert visited page content into numbered markdown for downstream processing
⚡ Developer Benefits
Structured page output via numbered markdown
Browser automation primitives aligned to reading and interaction
⚠️ Limitations
Limited scope can be inferred to browsing, reading, clicking, typing, and handing off (no other capabilities stated)
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.
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, 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: 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).
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).
Standard protocols. Every browser exposes CDP for Playwright, Puppeteer and similar
clients, and an MCP endpoint for AI assistants.
An agent completes a prior authorization in a mock payer portal
An agent session in the Oya desktop app, accelerated. The portal and patient data are fictional.
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:
Save the following as agent.mjs and run node agent.mjs:
js
import { Oya } from'@oya-ai/browser';
const browser = awaitnewOya().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,
export only OYA_API_KEY, and run the same sample. start() uses the
Oya desktop app 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:
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:
Install the desktop app, 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:
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 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/ 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.
Self-hosted deployments include host-level egress rules and a tamper-evident audit trail. See the
control evidence and the trust center.
To report a vulnerability, follow SECURITY.md.
An enterprise edition, including a HIPAA-ready offering, is maintained separately. Contact
sales@getoya.ai.
The SDK and CLI are licensed under MIT. All other components are available under the Sustainable
Use License. See LICENSE.md for permitted use, self-hosting terms and commercial
licensing.
Install
Remote endpoint
Streamable HTTP
Hosted server - connect over the network, no local install.