Skip to content
Skills Library
Programming · Testing

agent-qa-plugin-hyperbrowser

/agent-qa-plugin-hyperbrowser

Use when configuring agent-qa web tests to run in Hyperbrowser cloud browsers through the Hyperbrowser plugin, or when a Hyperbrowser remote is refused.

Repository
agent-qa ↗
Licence
Apache-2.0
Last repository change
11.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when configuring agent-qa web tests to run in Hyperbrowser cloud browsers through the Hyperbrowser plugin, or when a Hyperbrowser remote is refused.

Original author description

Use when configuring agent-qa web tests to run in Hyperbrowser cloud browsers through the Hyperbrowser plugin, or when a Hyperbrowser remote is refused.

How it works

  1. Declare the plugin and a remote
  2. Settings
  3. When a remote is refused
  4. Recording
  5. Check and describe
Original SKILL.md headings · 103 lines, 767 words
SKILL.md preview
---
name: agent-qa-plugin-hyperbrowser
description: Use when configuring agent-qa web tests to run in Hyperbrowser cloud browsers through the Hyperbrowser plugin, or when a Hyperbrowser remote is refused.
---

# Hyperbrowser remotes for agent-qa

The Hyperbrowser plugin gives an agent-qa web test a Hyperbrowser browser session. Before the test
connects it creates a session through Hyperbrowser's API, and after the test it stops the session.
Hyperbrowser runs Chromium only. Stealth, proxies, CAPTCHA solving, ad, tracker and annoyance
blocking and cookie auto-accept are off unless a setting turns them on, so a test sees the app the
way its users do.

## Declare the plugin and a remote

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

- The `plugins` entry holds the account: `apiKey`, which is required, and `apiUrl`, which defaults
  to `https://api.hyperbrowser.ai`. Write the key as a `{{secret:<name>}}` reference to a name in
  the file `workspace.secretsFile` names. Never write the key itself in the config.
- The remote holds one place: `plugin` names the `plugins` entry, and `settings` hold that place's
  Hyperbrowser settings.
- `use.browser.remote: hyperbrowser` in the config, a suite or a test runs the test there.
- Add the plugin with `npx agent-qa plugins add @vostride/agent-qa-plugin-hyperbrowser`: it pins the
  package at the project's agent-qa version and writes the `plugins` entry. `agent-qa plugins list`
  prints that line when the package is missing or the version differs.

## Settings

- `timeoutMinutes` (default `720`, 1 to 720): minutes before Hyperbrowser stops the session. It
  overrides the team default in Hyperbrowser's settings. The plugin never asks for keep-alive, so
  Hyperbrowser also stops a session whose connection drops, and agent-qa stops every session after
  its test. A session whose create was in flight when the job was killed was never connected, so
  it runs until `timeoutMinutes`.
- `recording` (unset by default): Hyperbrowser's web recording. Unset keeps the account's default,
  which records. `recording: false` turns it off.
- `stealth`, `solveCaptchas`, `adblock`, `trackers`, `annoyances`, `acceptCookies` (each default
  `false`): Hyperbrowser's stealth mode, CAPTCHA solving, ad, tracker and annoyance blocking and
  automatic acceptance of cookie banners.
- `proxy` (default `false`): `true`, or `{ country, state, city }` with any of the three. Proxies
  and CAPTCHA solving need a paid Hyperbrowser plan.
- `screen` (`{ width, height }` in pixels), `region` (for example `us-east` or `europe-west`),
  `extensions` (extension ids): Hyperbrowser's own create fields, sent only when set.
- `profile`: a Hyperbrowser profile id. It loads read-only: nothing the test does is saved back. It
  needs `context: reuse` on the remote, because the profile lives in the browser's first context:

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

- `extra`: any other Hyperbrowser request field. It is merged last, so it overrides the settings
  above. Video replay is `extra: { enableVideoWebRecording: true }`, and needs recording on.
  Enterprise proxy servers go here as `proxyServer`, `proxyServerUsername` and
  `proxyServerPassword`; write the password as a `{{secret:<name>}}` reference.

## When a remote is refused

- `auth`: Hyperbrowser refused the API key. Check the secret's value.
- `capacity`: Hyperbrowser answered 429. The account has no free sessions, or is rate limited.
  Wait, or lower the run's concurrency.
- `refused` with `Hyperbrowser answered 403 to POST /api/session: <reason>`: a feature the remote
  turns on is not on the plan, for example `Proxy usage requires a paid plan`. Turn that setting
  off, or change the plan.
- `refused` with path `settings.profile`: the remote sets `profile` without `context: reuse`. Add
  `context: reuse` to the remote.
- `refused` with path `settings.timeoutMinutes`: the lifetime is outside 1 to 720. Set a value in
  that range, or leave it out for 720.
- `refused` naming a browser or platform: Hyperbrowser runs Chromium web tests only. Use
  `use.browser.name: chromium`, or another remote.
- `refused` at `options.apiUrl`: the endpoint must use `https://` with no user or password, unless
  it points at this machine.
- `unreachable`: Hyperbrowser could not be reached. Check the network and `apiUrl`.

## 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 the remote to turn recording off. The session link opens the session's page
in Hyperbrowser's dashboard. Hyperbrowser's live view URL and the session token let anyone who has
them watch and drive the session, so agent-qa masks both and never shows them as the link.

## Check and describe

- `agent-qa doctor` runs the plugin's account check. It reads the active sessions to prove the key,
  reports how many there are, and opens none.
- `agent-qa plugins describe hyperbrowser --json` lists every option and setting with its type,
  default and description.

Versions

The database has no other skills named agent-qa-plugin-hyperbrowser.

Database snapshot: 13.11.2026 · package version 648311171fc5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95agent-qa-plugin-kernel
    Use when configuring agent-qa web tests to run in Kernel cloud browsers through the Kernel plugin, or when a Kernel remote is refused.
  • 95agent-qa-plugin-steel
    Use when configuring agent-qa web tests to run in Steel cloud browsers through the Steel plugin, or when a Steel remote is refused.
  • 100hyperbrowser-mcp
    Hyperbrowser Model Context Protocol (MCP) server for cloud headless browser automation, dynamic SPA crawling, session recording, and stealth web scraping (hyperbrowserai/mcp). Use when the agent needs to render complex JavaScript single-page apps, crawl websites, or execute browser agents.
  • 100migrate-to-notte
    Cost-compare and migrate browser automation from Browserbase and Stagehand, Kernel, Anchor Browser, Browser Use Cloud, Steel, Hyperbrowser, or Skyvern to Notte. Use when a user wants a provider-to-Notte cost comparison, browser-minute or concurrency model, savings business case,…
  • 100web-testing
    Tests web applications in real browsers with Playwright end-to-end automation. Use when writing *.spec.ts files, playwright.config.ts or an e2e CI job, when a browser test is flaky or times out, when reusing login state or mocking the network, or when choosing component versus end-to-end tests.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.