# 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.139-universal.dmg) |
| Windows (x64) | [Oya Browser.exe](https://oyabrowser.com/downloads/Oya.Browser-1.0.139-x64.exe) |
| Linux (x64) | [Oya Browser.AppImage](https://oyabrowser.com/downloads/Oya.Browser-1.0.139-x64.AppImage) |

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

**Linux:** `chmod +x` the AppImage and run it.

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

# Linux
./Oya-Browser.AppImage --user-data-dir=/tmp/oya-2
```

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

## Connect a desktop browser

Open Oya Browser. The setup screen appears on first launch.

| Field | Value |
| --- | --- |
| Server URL | `wss://oyabrowser.com/ws` |
| API Key | The key you generated in the dashboard |
| Browser Name | Optional, how it shows in the dashboard |

Click **Connect**. The green dot in the toolbar confirms the connection. Your browser now appears in the [dashboard](https://oyabrowser.com/dashboard).