--- title: "v0.2.x to v0.3.x" description: "Upgrade agent-qa from v0.2 to v0.3: remote browsers and devices, first-party plugins, devices described by model, and every removed key with what replaces it." canonical_url: "https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3" md_url: "https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3.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. # v0.2.x to v0.3.x > Upgrade agent-qa from v0.2 to v0.3: remote browsers and devices, first-party plugins, devices described by model, and every removed key with what replaces it. ## What's new agent-qa v0.3 can run tests somewhere other than your machine, and describes every device in the committed config. - **Remote browsers and devices.** List a Playwright server, a CDP endpoint or an Appium server under `registry.remotes`, and pick it with `use.browser.remote` or a device's `remote`. See [Remote browsers and devices](https://vostride.com/docs/agent-qa/guides/remotes.md). - **First-party plugins.** [BrowserStack](https://vostride.com/docs/agent-qa/plugins/browserstack.md), [Hyperbrowser](https://vostride.com/docs/agent-qa/plugins/hyperbrowser.md), [Kernel](https://vostride.com/docs/agent-qa/plugins/kernel.md) and [Steel](https://vostride.com/docs/agent-qa/plugins/steel.md) each have a plugin that creates a session before a test and releases it after. `plugins` is now one list of named entries, and the [plugin kit](https://vostride.com/docs/agent-qa/plugins/write-a-plugin.md) lets you write your own. - **Devices by model.** A device says what it is, such as `model: Pixel 8` and `os: "15"`, and agent-qa finds it on this machine. A target names its default `device`. `agent-qa devices` shows where each device runs and what this machine has. - **New commands.** `agent-qa plugins list`, `agent-qa plugins describe `, `agent-qa plugin validate `, `agent-qa devices` and `agent-qa doctor --remote `. ## How to upgrade v0.3 upgrades in place. Your tests, suites, hooks, knowledge and recorded runs carry over; only some config keys change. **Upgrade this project to agent-qa v0.3** ```text Upgrade this project from agent-qa v0.2 to v0.3. Do the work, rather than only describing it. Read the upgrade guide first: https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3.md v0.3 upgrades in place. Keep the tests, suites, hooks, knowledge and recorded runs. 1. Find agent-qa.config.yaml and the files it names. Stop any agent-qa dashboard or MCP server you started. 2. Upgrade agent-qa with this repository's package manager. If the project uses a Claude or Codex subscription, upgrade @vostride/agent-qa-subscription-auth too. 3. Run npx agent-qa validate. Every removed key is refused with a sentence that says what to do. Fix each one, using the tables in the guide. 4. If agent-qa.local.yaml exists, move each device into registry.devices in agent-qa.config.yaml, described by model and os, and each app path into its target's app.path, and set the target's device. Run npx agent-qa devices to see the model names this machine has. Then delete agent-qa.local.yaml. 5. If the project ran on BrowserStack, install @vostride/agent-qa-plugin-browserstack at exactly the agent-qa version, and add its plugins entry, remote and devices as the guide shows. Ask me to put BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in the secrets file; never write their values yourself. 6. Run npx agent-qa validate until it passes, then npx agent-qa doctor and npx agent-qa plugins list, and fix what they report. 7. Run one of my own tests or suites and report its verdict. Never print secrets or put credentials in YAML or commands. Report what you changed, and anything I still need to do. ``` ### Update the packages ```bash npm install -D agent-qa@latest ``` If you sign in with a Claude or Codex subscription, update `@vostride/agent-qa-subscription-auth` to the latest version too. ### Validate ```bash npx agent-qa validate ``` Every removed key is refused with one sentence that says what to do, and a leftover `agent-qa.local.yaml` stops every command that loads the config. Work through them with the tables below. ### Check the setup ```bash npx agent-qa devices npx agent-qa doctor ``` Then run one of your own tests or suites. ## What changed in your files ### plugins `plugins` is a list of named entries, and `plugins.auth` is gone. The subscription sign-in plugin becomes the `subscription` entry: ```yaml # v0.2 plugins: auth: - package: "@vostride/agent-qa-subscription-auth" ``` ```yaml # v0.3 plugins: - name: subscription package: "@vostride/agent-qa-subscription-auth" ``` `plugins.providers` is gone. A model provider plugin must be an `@vostride/agent-qa-*` package, so a third-party one is refused; use `openai-compatible` or `anthropic-compatible` with a `baseURL` instead. ### agent-qa.local.yaml agent-qa no longer reads `agent-qa.local.yaml`, and refuses to start while the file exists: ```text agent-qa.local.yaml is no longer read: describe each device under registry.devices with model and os (id pins one unit), and set app.path on the target. Delete the file. ``` Move each part into `agent-qa.config.yaml`, then delete the file: ```yaml # v0.2: agent-qa.config.yaml registry: devices: pixel: platform: android transport: local targets: my-app: platform: android appPackage: com.example.app appActivity: .MainActivity ``` ```yaml # v0.2: agent-qa.local.yaml devices: pixel: avd: Pixel_8_API_35 apps: my-app: path: builds/my-app-debug.apk ``` ```yaml # v0.3: agent-qa.config.yaml registry: devices: pixel: platform: android model: Pixel 8 targets: my-app: platform: android appPackage: com.example.app appActivity: .MainActivity device: pixel app: path: builds/my-app-debug.apk ``` | v0.2 binding | v0.3 | | --- | --- | | `devices..avd` | `model`: the AVD's name or its device profile. `agent-qa devices` lists them. | | `devices..serial` | `model`: the model the phone reports. Add `id` with the serial only when two identical phones are attached. | | `devices..udid` | `model`: the simulator's name. Add `id` with the UDID only to pick one of two identical simulators. | | `devices..platformVersion` | `os`, in quotes. | | `devices..appPackage`, `appActivity`, `bundleId` | The target's `appPackage`, `appActivity` and `bundleId`. | | `devices..automationName`, `browserName` | The device's `capabilities`, as `appium:automationName` and `browserName`. | | `apps..path` | The target's `app.path`. | | `apps..browserstack` | The target's `app.ref`. | | `providers.browserstack` | The [BrowserStack plugin](https://vostride.com/docs/agent-qa/plugins/browserstack.md), with the credentials in your secrets file. | ### registry.devices | v0.2 | v0.3 | | --- | --- | | `transport: local` | Delete it. A device with no `remote` is on this machine. | | `transport: browserstack` | Set `remote` to a [BrowserStack](https://vostride.com/docs/agent-qa/plugins/browserstack.md) plugin remote. | | `match` | Describe the device with `model`, `os` and `id`. App IDs go on the target, and other Appium settings go in `capabilities`. | A test without `use.device` now runs on its target's `device`. `--device` still picks a device for a run, but only one on this machine. ### BrowserStack agent-qa no longer reads `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` from the environment, and has no built-in BrowserStack transport. Install the plugin, put the two values in your secrets file, and add an entry and a remote: ```bash npm install --save-dev --save-exact @vostride/agent-qa-plugin-browserstack@$(npx agent-qa --version) ``` ```yaml plugins: - name: browserstack package: "@vostride/agent-qa-plugin-browserstack" options: username: "{{secret:BROWSERSTACK_USERNAME}}" accessKey: "{{secret:BROWSERSTACK_ACCESS_KEY}}" registry: remotes: - name: browserstack-devices plugin: browserstack devices: bs-pixel: platform: android remote: browserstack-devices model: Google Pixel 9 os: "15" ``` A target's `app.browserstack` becomes `app.ref`, or leave `app.ref` out and the plugin uploads `app.path` for you. `registry.providers` is gone. ### Other removed keys These went away in late v0.2 releases. Each one is refused with a message that says what to do. | Key | Instead | | --- | --- | | `allowProduction` | Delete it. A target's `environment` is a label, and production targets run like any other. | | `eval` | Delete it. `agent-qa eval replay` takes its settings as flags. | | `services.cache.ttl` | Delete it. Cached plans do not expire by age. | | `services.mcp.host`, `path`, `transport` | Delete them. `agent-qa mcp` listens on `127.0.0.1`, and uses stdio or `--http`. | | `services.accessibility.runAfter: navigation` | Use `test-end` or `every-step`. | | `knowledge.contextBudgetTokens`, `knowledge.commitArtifacts` | Delete them. | | A step's `retries` | Set `meta.retries` on the test: a test retries as a whole. | | A step's `screenshot` | Pass `--screenshot-mode every-step` to `agent-qa run`. | ### Commands | v0.2 | v0.3 | | --- | --- | | `agent-qa devices init` | Removed. Devices are found by model, so nothing needs binding. Run `agent-qa devices` to see what this machine has. | | `agent-qa run --bail`, `--screenshot-dir`, `--max-ablations` | Removed. | | `agent-qa cache purge --test ` | Removed. `cache purge --all` clears every cached plan. | | `AGENT_QA_CACHE_TTL` | No longer read. | | `AGENT_QA_APPIUM_URL` | Names an Appium server on this machine only. List any other server under `registry.remotes`. | ## Documentation navigation - [All documentation](https://vostride.com/docs.md) - Parent: [What is agent-qa](https://vostride.com/docs/agent-qa.md) - Previous: [Variables and secrets](https://vostride.com/docs/agent-qa/configuration/env-secrets.md) - Next: [v0.1.x to v0.2.x](https://vostride.com/docs/agent-qa/migrate/v0-1-to-v0-2.md)