This repository contains the Oya Browser community edition. People and AI agents work
together in one browser: agents can use an existing signed-in browser, start managed cloud
browsers, or connect through familiar tools and APIs. People can watch the work, step in when
needed, and keep control of browser access and repeatable tasks.
The enterprise edition, including the HIPAA-ready offering, is maintained in a separate private
repository. Contact [email protected] to learn about that edition.
Choose how to get started
Use Oya with an AI assistant
Install the desktop app, sign in, and connect your assistant
from the app. Oya works with Claude Code, Codex, Cursor and VS Code. People can see the agent's
browser activity and take control when a task needs their attention.
Download the desktop app · Agent setup guide
Control a browser from Node.js
Install the SDK and create an API key at oyabrowser.com. Node.js 20 or
newer is required.
npm install @oya-ai/browser
Set OYA_API_KEY, then run:
import { Oya } from '@oya-ai/browser';
const oya = new Oya();
const browser = await oya.browser.start();
try {
await browser.goto('https://news.ycombinator.com');
console.log(await browser.ask('Summarize the top three stories.'));
} finally {
await browser.stop();
}
With no browser provider configured, start() can use the Oya desktop browser already connected
to your account. To start cloud or self-hosted browsers, configure a provider with
npx @oya-ai/cli init. The SDK and CLI can also use Browserbase, Steel,
Anchor, Browser Use, or a browser you provide. Your application can keep the same SDK calls when
you change providers.
SDK guide · Runnable examples · CLI guide
Connect over MCP
For assistants that support remote MCP, connect to https://oyabrowser.com/mcp/pool and
authenticate with your Oya API key. For Claude Code:
claude mcp add --transport http oya https://oyabrowser.com/mcp/pool \
--header "Authorization: Bearer $OYA_API_KEY"
Use the same endpoint with your self-hosted server URL when you run your own deployment.
Agent instructions and MCP reference
For AI agents
Use the agent reference for setup instructions, available
tools, SDK examples, and MCP configuration. The desktop app can pair with Claude Code, Codex,
Cursor, and VS Code. For remote MCP clients, connect to https://oyabrowser.com/mcp/pool with
your Oya API key.
Run Oya in your own environment
Use the installer to set up a self-hosted instance:
curl -fsSL https://raw.githubusercontent.com/OyadotAI/oya-browser/main/install.sh | sh
For production, choose Docker, Amazon ECS, Kubernetes, or GKE. The deployment guides cover
configuration, storage, upgrades, and operations.
Self-hosting guide · Deployment templates
What you can do with Oya
- Work in a signed-in browser. Connect the desktop app and reuse logins imported from Chrome,
Arc, Brave, Edge, or Firefox. Set up logins.
- Keep a person in control. Watch an agent work, switch between AI Mode and Human Mode, and
keep agent activity in its own tabs.
- Turn a successful run into a playbook. Replay repeatable tasks with new inputs, inspect the
generated Playwright module, and export or import workflows.
Playbook details ·
Replay benchmark.
- Choose where browsers run. Use Oya Cloud, your own deployment, supported browser providers,
or a browser you provide. Why route through Oya?.
- Operate with governance controls. Self-hosted community deployments include host egress
rules and a tamper-evident audit trail. See the control evidence and
trust center.
For contributors
Oya is made up of the browser, control plane, console, SDK, and CLI. Start with the architecture
map, then read the guide for the part you plan to change.
Development
Requirements and commands vary by project area. See Working in this repository for
the conventions and complete command list. To install dependencies across the workspace:
npm run setup
Common checks:
npm run lint
npm run format:check
npm test
The full test command builds the SDK and runs the server, CLI, package, and script suites. For
changes in the UI or browser app, run the checks listed in that part's package.json and
architecture guide as well.
Packages and project areas
| Path | What it contains |
|---|
packages/sdk | @oya-ai/browser, the TypeScript SDK (MIT) |
packages/cli | @oya-ai/cli, setup and command-line tools (MIT) |
browser | Oya's desktop browser and cloud browser image |
server | API, browser connections, MCP, and control plane |
ui | Web console and public site |
examples | SDK and browser integration examples |
docs | Operator guides and product details |
License
The SDK and CLI are MIT licensed. The rest of the project is available under the Sustainable Use
License. See LICENSE.md for permitted use, self-hosting terms, and commercial
licensing details.
