Browser

Oya Browser docs

Quickstart, API keys and desktop sign-in

Get an API key, run a task once with an agent and replay it with no model, in about three minutes. Then sign in on the desktop and connect a browser.

Quickstart

Three steps, about three minutes. You end with a task your code replays with no model.

Get an API key

Open the console, create a key from the API key menu, and export it.

Terminal
export OYA_API_KEY=oya_...

Install the SDK

Terminal
npm i @oya-ai/browser

Run a task, save it, replay it

first-run.mjs
import { Oya } from "@oya-ai/browser";

const oya = new Oya();                          // reads OYA_API_KEY
const browser = await oya.browser.start();      // a real browser, not headless Chrome

try {
  // 1. Do the task once, in plain language. The model works it out.
  await browser.ask(
    "On https://httpbin.org/forms/post order a medium pizza for {{name}} and submit it.",
    { data: { name: "Ada Lovelace" } },
  );

  // 2. Save that run as a playbook: Playwright steps, with your values as variables.
  const playbook = await browser.toPlaybook("pizza-order");
  console.log(playbook.variables);              // the inputs play() takes

  // 3. Replay it with new values. No model, no tokens.
  console.log(await browser.play("pizza-order", { name: "Grace Hopper" }));
} finally {
  await browser.close();                        // stop paying for it, even on an error
}

That is the loop: ask once, replay forever. From here, read for variables, free-text fields and healing, or to hand the browser to Claude or Cursor.

From a terminal instead

Terminal
npm i -g @oya-ai/cli
oya login && oya start
oya ask "find the pricing page on example.com"
Everything belongs to the API key: browsers, personas, cookies, playbooks, settings and usage. One key never sees another's. Which provider runs the browser is a setting on the key, chosen during , so your code never changes.

API keys

Go to the dashboard. Open the API key menu to create or select a key for your workspace.

Your key is scoped: you only see browsers connected with your key. Other users' browsers are invisible to you.

Save your key somewhere safe. If you lose it, you'll need to generate a new one. The old key still works for any browsers already connected with it.

Desktop sign-in

For browsers on Oya infrastructure, the desktop app is a one-time step: log into the sites your agents need, and those cookies move to the remote browsers, which run the same fingerprint as that identity. The agent arrives already signed in, and the site sees one device returning rather than a fleet sharing an account.

Onboarding and Settings both have an Open the desktop browser button. It builds an oya:// link carrying a single-use pairing code, never your API key, because a protocol URL is reachable by any page you visit and lands in OS logs on the way. The app exchanges that code over HTTPS with the server the link names.

The desktop app asks before connecting, naming the destination host, with Cancel as the default. Connecting shares that browser's cookies and logged-in sessions with the control plane it dials, so if a web page opened the dialog rather than your own dashboard, cancel it.
PlatformDownload
macOS (Intel + Apple Silicon)Oya Browser.dmg
Windows (x64)Oya Browser.exe

macOS: Open the .dmg and drag the app to Applications. The build is signed and notarized, so it opens normally. If an older download is blocked, right-click the app → Open → Open.

Windows: Run the .exe installer and follow the setup prompts.

Running multiple instances

To open multiple browser windows (e.g. different accounts or different API keys):

Example
# macOS, open another instance
open -n "/Applications/Oya Browser.app"

# With separate sessions (own cookies, own config)
open -n "/Applications/Oya Browser.app" --args --user-data-dir=/tmp/oya-2
open -n "/Applications/Oya Browser.app" --args --user-data-dir=/tmp/oya-3

Each --user-data-dir gets its own cookies, logins, and config, fully isolated sessions.

Connect a desktop browser

Open Oya Browser. The first screen asks how you want to start.

Pick a starting point

Technical: sign in with Oya, connect a local agent (Claude Code, Codex, Cursor or VS Code) or paste a model API key. Non-technical: connect the assistant you already pay for, ChatGPT or Claude, and type tasks in Oya's Ask panel. AI expert: sign in to your Oya workspace and walk through the control plane; a server URL and Oya key is still there as the second button.

Connect your agent from the footer

Every coding agent installed on this computer gets a Connect button in the Oya window footer. One click writes an MCP server named oya-browser at http://127.0.0.1:47321/mcp into that agent's config, with the token kept in the OS keychain. Click again to remove it.

Bring your logins

Accept Bring your logins to import saved logins from Chrome, Arc, Brave, Edge, Firefox or Safari, so sites are already signed in. Bookmarks and history are a separate, optional step you can skip.

Start a new session

Restart your agent's session so the oya-browser tools appear. Each session drives its own tab, marked in the tab strip; you keep every other tab and can take control at any time.

If you signed in with Oya, the browser also appears in the dashboard. Local agents connected from the footer need no account and no key.