# Get started

Part of the Oya Browser docs. All of it: https://oyabrowser.com/docs.md

## Quickstart

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

### Get an API key

Open the [console](https://oyabrowser.com/dashboard), create a key from the API key menu, and export it.

```
export OYA_API_KEY=oya_...
```

### Install the SDK

```
npm i @oya-ai/browser
```

### Run a task, save it, replay it

```
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 Playbooks for variables, free-text fields and healing, or MCP to hand the browser to Claude or Cursor.

### From a terminal instead

```
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 onboarding, so your code never changes.

## API keys

Go to the [dashboard](https://oyabrowser.com/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.

| Platform | Download |
| --- | --- |
| macOS (Intel + Apple Silicon) | [Oya Browser.dmg](https://oyabrowser.com/downloads/Oya.Browser-1.0.240-universal.dmg) |
| Windows (x64) | [Oya Browser.exe](https://oyabrowser.com/downloads/Oya.Browser-1.0.240-x64.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):

```
# 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](https://oyabrowser.com/dashboard). Local agents connected from the footer need no account and no key.
