---
title: "Hyperbrowser"
description: "Run agent-qa web tests in Hyperbrowser cloud browsers: install the Hyperbrowser plugin, add a remote, turn recording off, use profiles and proxies, and fix refusals."
canonical_url: "https://vostride.com/docs/agent-qa/plugins/hyperbrowser"
md_url: "https://vostride.com/docs/agent-qa/plugins/hyperbrowser.md"
last_updated: "2026-11-07T15:25:39+05:30"
---

> [Documentation index](https://vostride.com/docs.md) · [Site index](https://vostride.com/llms.txt)
> Follow the Markdown links to read individual pages; the indexes list the available documentation.

# Hyperbrowser

> Run agent-qa web tests in Hyperbrowser cloud browsers: install the Hyperbrowser plugin, add a remote, turn recording off, use profiles and proxies, and fix refusals.

The Hyperbrowser plugin, `@vostride/agent-qa-plugin-hyperbrowser`, gives each web test a [Hyperbrowser](https://hyperbrowser.ai) browser session. Before the test connects, it creates the session through Hyperbrowser's API and hands agent-qa its CDP address. After the test it stops the session.

Hyperbrowser runs Chromium only, so tests on a Hyperbrowser remote use `use.browser.name: chromium`. Stealth, proxies, CAPTCHA solving, ad, tracker and annoyance blocking and cookie banner acceptance are off unless a setting turns them on, so a test sees your app the way your users do.

## Install
Install the plugin at exactly the version of agent-qa your project runs:

```bash
npm install --save-dev --save-exact @vostride/agent-qa-plugin-hyperbrowser@$(npx agent-qa --version)
```

## Configure
```yaml
plugins:
  - name: hyperbrowser
    package: "@vostride/agent-qa-plugin-hyperbrowser"
    options:
      apiKey: "{{secret:HYPERBROWSER_API_KEY}}"

registry:
  remotes:
    - name: hyperbrowser
      plugin: hyperbrowser
    - name: hyperbrowser-unrecorded
      plugin: hyperbrowser
      settings:
        recording: false

use:
  browser:
    name: chromium
    headless: true
    remote: hyperbrowser
```

Put the key in your secrets file, `.env.secrets.local` by default, as `HYPERBROWSER_API_KEY=...`.

## Options
Options belong to the `plugins` entry and describe the account.

| Option | Default | Meaning |
| --- | --- | --- |
| `apiKey` | required | The Hyperbrowser API key, a credential. Write it as a `{{secret:NAME}}` reference. |
| `apiUrl` | `https://api.hyperbrowser.ai` | Hyperbrowser's API. It must use `https://` with no user or password, unless it points at this machine. |

The key is sent only as the `x-api-key` header, and never appears in logs, run records or `doctor` output.

## Settings
Settings belong to each remote and describe one place.

| Setting | Default | Meaning |
| --- | --- | --- |
| `timeoutMinutes` | `720` | Minutes before Hyperbrowser stops the session, from 1 to 720. It overrides your team's default. |
| `recording` | | Hyperbrowser's web recording. Unset keeps your account's default, which records. `false` turns it off. |
| `stealth` | `false` | Hyperbrowser's stealth mode, which changes what pages see. |
| `proxy` | `false` | Hyperbrowser's proxy: `true`, or `{ country, state, city }` with any of the three. |
| `solveCaptchas` | `false` | Hyperbrowser's CAPTCHA solving. |
| `adblock` | `false` | Ad blocking. |
| `trackers` | `false` | Tracker blocking. |
| `annoyances` | `false` | Annoyance blocking. |
| `acceptCookies` | `false` | Accepting cookie banners automatically. |
| `screen` | | The browser screen, `{ width, height }` in pixels. |
| `region` | | The Hyperbrowser region, such as `us-east` or `europe-west`. |
| `profile` | | A Hyperbrowser profile ID, loaded read-only. Needs `context: reuse`. |
| `extensions` | | Hyperbrowser extension IDs to load into the browser. |
| `extra` | | Any other field of Hyperbrowser's create request, merged last. |

Proxies and CAPTCHA solving need a paid Hyperbrowser plan.

## How the request is built
The plugin builds Hyperbrowser's create request in this order, each part overriding the one before:

1. the lifetime, `timeoutMinutes`;
2. the features that change the page, each sent off unless a setting turns it on;
3. the proxy fields: `proxy: true` turns Hyperbrowser's proxy on, and a proxy object also sends the country, state and city it gives;
4. the other settings, each only when it is set;
5. `extra`, last, so a field there overrides both a default and a setting.

For example, `settings: { extra: { useUltraStealth: true } }` asks for Hyperbrowser's Enterprise stealth mode. Enterprise proxy servers go through `extra` too, with the password as a secret reference:

```yaml
settings:
  extra:
    proxyServer: "http://proxy.example.com:8080"
    proxyServerUsername: "<proxy user>"
    proxyServerPassword: "{{secret:HYPERBROWSER_PROXY_PASSWORD}}"
```

## Lifetime and disconnects
By default the plugin asks for a 720-minute session, the longest Hyperbrowser allows. agent-qa stops every session itself after its test; the lifetime only bounds a session it could not stop.

The plugin never asks Hyperbrowser to keep a session alive, so Hyperbrowser stops a session whose connection drops. A session left behind by a killed job stops with its connection. If a job is killed while a session is still being created, that session was never connected, so it runs until `timeoutMinutes`. Lower `timeoutMinutes` to bound it.

## Recording
Hyperbrowser records sessions by default and keeps the replay on its dashboard, behind its login. agent-qa's masking does not reach that replay, so a secret a test types may show in it. Set `recording: false` on a remote to turn recording off for its sessions, as `hyperbrowser-unrecorded` does above.

Video replay is off unless you ask for it with `extra: { enableVideoWebRecording: true }`. It needs web recording, so do not combine it with `recording: false`.

The session link is the session's page in Hyperbrowser's dashboard, returned only when it is an `https://` URL. Hyperbrowser's live view URL and session token let anyone who has them watch and drive the session, so agent-qa masks both and never shows them.

## Signed-in profiles
`profile` loads a Hyperbrowser profile by ID, and nothing a test does is saved back to it. A profile lives in the browser's first context, so the remote needs `context: reuse`:

```yaml
registry:
  remotes:
    - name: hyperbrowser-signed-in
      plugin: hyperbrowser
      context: reuse
      settings:
        profile: <Hyperbrowser profile ID>
```

## Account check
`agent-qa doctor` runs the plugin's account check, which reads your active sessions and opens none:

- an accepted key reads `the API key was accepted`, with the number of active sessions when Hyperbrowser gives it, such as `2 active sessions`;
- a refused key warns `the API key was refused`.

## When a remote is refused
| Kind | Cause | Fix |
| --- | --- | --- |
| `auth` | Hyperbrowser responded with 401. | Check the key in your secrets file. |
| `capacity` | Hyperbrowser responded with 429: no free sessions, or a rate limit. | Wait, or lower `use.workers`. |
| `refused`, `Hyperbrowser answered 403 to POST /api/session: <reason>` | A feature the remote turns on is not on your plan, such as `Proxy usage requires a paid plan`. | Turn that setting off, or change the plan. |
| `refused` at `settings.profile` | The remote sets `profile` without `context: reuse`. | Add `context: reuse` to the remote. |
| `refused` at `settings.timeoutMinutes` | The lifetime is outside 1 to 720. | Set a value in range, or leave it out for 720. |
| `refused` naming a browser | Hyperbrowser runs Chromium only. | Use `use.browser.name: chromium`, or another remote. |
| `refused` at `options.apiUrl` | The endpoint is not `https://` and not this machine. | Use `https://`. |
| `unreachable` | Hyperbrowser did not respond. | Check the network and `apiUrl`. |

Hyperbrowser chooses the session ID, so when a create request fails there is no session to stop. On release, a session Hyperbrowser has already stopped counts as stopped.

`npx agent-qa plugins describe hyperbrowser --json` lists every option and setting with its type, default and description.

## Documentation navigation

- [All documentation](https://vostride.com/docs.md)
- Parent: [Plugins](https://vostride.com/docs/agent-qa/plugins.md)
- Previous: [BrowserStack](https://vostride.com/docs/agent-qa/plugins/browserstack.md)
- Next: [Kernel](https://vostride.com/docs/agent-qa/plugins/kernel.md)