Oya Browser

Oya Browser is a browser for AI agents that you can run on your own infrastructure or use as a managed service. 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.

• 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 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.

Requirements

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:

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:

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 replay submits the same order for a different name without calling the model. Output from one run with Gemini 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, 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:

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:

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 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:

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.

Samples

The examples directory contains runnable TypeScript samples. After the quickstart, 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 API key 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 the self-hosting guide and the deployment templates.

Security and compliance

Self-hosted deployments include host-level egress rules and a tamper-evident audit trail. See the control evidence and the [trust c