---
title: Quickstart
description: Install agent-qa, prepare web and mobile runtimes, connect an LLM, and inspect your first run from the dashboard or CLI.
---



agent-qa ships as an npm package. Add it to an existing codebase when you already have an app repository, or start a small JavaScript workspace when you want to try agent-qa beside a non-JavaScript project first.

## Prerequisites [#prerequisites]

* A JavaScript runtime such as [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.com/). agent-qa is written in JavaScript and needs a local runtime for the CLI and dashboard.
* Access to an LLM for inference. You can use a remote API endpoint, a local model served by tools such as [Ollama](https://ollama.com/) or [LM Studio](https://lmstudio.ai/), or subscription auth.
  * OpenAI-compatible API endpoints
  * Anthropic-compatible API endpoints
  * Gemini models
  * Codex or Claude Code subscriptions through the optional subscription auth plugin

<Info>
  Use a multimodal model for the normal quickstart. Web and mobile runs inspect screenshots, so text-only models are not a good fit for visual QA workflows.
</Info>

* Docker is optional, but recommended. agent-qa can run JavaScript, Python, Bash, and Bun hooks inside an isolated Docker runtime.

## Install agent-qa and prepare the environment [#install-agent-qa-and-prepare-the-environment]

agent-qa runs independently from the application under test, so you can install it in JavaScript, Rails, Django, Laravel, Go, Java, Swift, Kotlin, web, or mobile repositories. You only need enough Node.js tooling to install and run the CLI.

<CommandSnippet commands="[&#x22;node --version&#x22;, &#x22;npm --version&#x22;]" />

Skip this step when your repository already has a `package.json`. Otherwise, create one before installing agent-qa:

<CommandSnippet command="npm init -y" />

Install `agent-qa` as a dev dependency so every teammate and CI job can run the same version.

<PackageInstallTabs variant="add" title="Install agent-qa" />

If you want to use Codex or Claude Code subscription auth instead of provider API keys, install the optional [subscription auth package](https://github.com/vostride/agent-qa-subscription-auth).

<PackageInstallTabs variant="auth" title="Install subscription auth support" />

## Set up the testing environment [#set-up-the-testing-environment]

Let's set up the test environment by installing browser runtimes for web and the relevant platform tools for mobile.

### Web browsers [#web-browsers]

Install browser runtimes for web tests. These agent-qa-managed browsers do not replace or interfere with browsers you already have installed.

<PackageInstallTabs variant="install-browsers" title="Install browser support" />

### Mobile drivers [#mobile-drivers]

For Android or iOS tests, install the Appium runtime first:

<CommandSnippet commands="[&#x22;npm install -g appium&#x22;, &#x22;appium --version&#x22;]" />

Then install the relevant mobile drivers:

<PackageInstallTabs variant="install-mobile" title="Install mobile driver support" />

You also need the developer platform tools:

* Android: install [Android Studio or Android SDK platform tools](https://developer.android.com/studio), then set up an emulator or connect a real device.
* iOS: install [Xcode and command line tools](https://developer.apple.com/xcode/), then set up an iOS simulator or connect a real device.

### Hook runtime [#hook-runtime]

Hooks run in an isolated Docker environment. Install Docker from Docker's [Get Started page](https://www.docker.com/get-started/), start Docker Desktop or the Docker daemon, then confirm the CLI can reach it:

<CommandSnippet commands="[&#x22;docker --version&#x22;, &#x22;docker info&#x22;]" />

You only need Docker for tests or suites that use hooks. If your first run does not use hooks, you can set it up later.

## Initialize agent-qa [#initialize-agent-qa]

Run the init command to scaffold the config files, local settings, sample tests, and hook examples.

<PackageInstallTabs variant="init" title="Initialize agent-qa" />

### Verify the environment [#verify-the-environment]

Run the doctor command after initialization to validate the local runtime pieces before your first test run.

<PackageInstallTabs variant="doctor" title="Check agent-qa setup" />

The generated workspace usually looks like this. Exact sample file names can vary by version, but the shape is stable: project config at the root, optional hook scripts, suites, and tests. Select a file to inspect the generated content.

<QuickstartScaffoldExplorer />

Keep generated run artifacts out of commits unless your team intentionally stores them.

## Open the dashboard [#open-the-dashboard]

Start the local dashboard from the project root.

<PackageInstallTabs variant="dashboard" title="Open dashboard" />

The `--open` command opens the agent-qa dashboard in your default browser.
Before running your first test, connect the LLM model agent-qa should use. On the dashboard:

1. Go to `Config` > `LLM`.
2. Add an LLM configuration.
3. Choose the provider or subscription auth mode.
4. Test the connection.
5. Go to `Config` > `Execution Defaults` and select the new LLM configuration.
6. Save the config.

The dashboard writes back to your local config files, so review the diff the same way you would review any other project configuration change. Model secrets, such as API keys or auth tokens, are stored in `~/.agent-qa/auth.json`.

## Run your first test from the dashboard [#run-your-first-test-from-the-dashboard]

Use the generated sample before writing a custom test.

1. Go to `Tests`.
2. Select `Example passing test`.
3. Click `Run` or press `R`.

By default, runs execute in headless mode. Disable headless mode in the execution settings when you want to watch the browser or mobile session directly.

While the test is running, the live view shows the active execution. After the run completes, open the run view and inspect the full timeline:

* what the agent observed before each step
* how it planned the next action
* what it actually executed, such as clicking a button or filling an input
* how it verified the result
* how each assertion was evaluated, including the reasoning behind the pass or failure

This view is the fastest way to learn whether a failure came from product behavior, test wording, environment setup, or model interpretation.

## Run your first test from the CLI [#run-your-first-test-from-the-cli]

agent-qa is designed to work with teams at scale. Run the same tests from CI, release jobs, or post-deploy checks to catch regressions before they reach users.

For CI, start with a narrow command that targets the tests you trust, then expand to suites as coverage grows:

<CommandSnippet command="npx agent-qa run tests/example-pass.yaml" />

The dashboard and CLI share the same file-backed definitions and run artifact storage. Use the dashboard for rich local debugging and the CLI for repeatable automation.

Feel free to reach out if you face any issues.