Oya Browser

Oya Browser

Oya Browser is a browser for AI agents that you can run on your own infrastructure or use as amanaged service. An agent completes a task once in natural language; Oya records the steps as aplaybook that replays deterministically, without calling a model, and repairs individual stepswhen 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.

• Features
• Requirements
• Quickstart
• Usage
• Samples
• Deployment
• Security and compliance
• Documentation
• Support
• Contributing
• License

Features

• Record and replay. A successful ask() is saved with toPlaybook() and replayed withplay() using new inputs and no model calls. Each playbook is also exported as a Playwrightmodule. In a ten-site benchmark, nine sites replayed every recordedstep with healing disabled.
• Step repair. When a recorded step no longer matches the page, the agent completes that stepand the playbook is updated. Repair can be disabled per call.
• Stable browser identity. Personas bind a fingerprint, cookie store and proxy that persistacross sessions (stealth results: 0% headless on CreepJS, 31/31 onSannysoft).
• 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 theagent.
• 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 similarclients, and an MCP endpoint for AI assistants.

_{An agent session in the Oya desktop app, accelerated. The portal and patient data are fictional.}

Requirements

Quickstart

This quickstart installs the control plane and one browser on your machine with Docker, then runsa sample that records a task and replays it.

1. Install the control plane

Export a model API key, then run the installer:

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 theconnection settings. Export them:

export OYA_BASE_URL=http://localhost:3100
export OYA_API_KEY=oya_...

2. Install the SDK

npm install @oya-ai/browser

3. Run the sample

Save the following as agent.mjs and run node agent.mjs:

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 replaysubmits the same order for a different name without calling the model. Output from one run withGemini 3.8 Flash:

agent:  152.712s
replay: 14.246s, no model

Agent time depends on the model; replay time does not. To watch the session, openhttp://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 theOya desktop app when it is open and signed in, and otherwisestarts 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, passmodel to the client. The setting applies to that client only and is not saved:

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. WhenapiKey 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-useconnect without changes:

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, open it and clickConnect next to your agent (Claude Code, Codex, Cursor, VS Code and others appearwhen installed). That adds an MCP server named oya-browser athttp://127.0.0.1:47321/mcp to the agent's config; no account, no key. The agentthen 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. ForClaude Code:

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

Setup instructions written for agents are published atoyabrowser.com/llms.txt.

Samples

The examples directory contains runnable TypeScript samples. After thequickstart, the installer's copy is ready to use:

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

The local installation runs one Docker browser. For samples that require Oya Cloud, use an APIkey from oyabrowser.com and leave OYA_BASE_URL unset.

Deployment

The quickstart installs a single-node deployment with SQLite and one browser. For production,including Postgres, multiple browsers, Amazon ECS, Kubernetes and GKE, see theself-hosting guide and the deployment templates.

Security and compliance

Self-hosted deployments include host-level egress rules and a tamper-evident audit trail. See thecontrol evidence and the trust center.To report a vulnerability, follow SECURITY.md.

An enterprise edition, including a HIPAA-ready offering, is maintained separately. Contact[email protected].

Documentation

Support

• Questions and discussion: Discord
• Bug reports and feature requests: GitHub Issues
• Commercial licensing and enterprise: [email protected]

Contributing

Contributions are welcome. To set up a development environment:

git clone https://github.com/OyadotAI/oya-browser.git && cd oya-browser
npm run setup

Read ARCHITECTURE.md for an overview of the codebase and AGENTS.mdfor conventions and the checks each part requires.

License

The SDK and CLI are licensed under MIT. All other components are available under the SustainableUse License. See LICENSE.md for permitted use, self-hosting terms and commerciallicensing.