--- title: "Quickstart" description: "Install agent-qa with Node.js or Bun, connect an OpenAI, Anthropic, Gemini, or local LLM, prepare web and mobile runtimes, then inspect your first run end to end." canonical_url: "https://vostride.com/docs/agent-qa/quickstart" md_url: "https://vostride.com/docs/agent-qa/quickstart.md" last_updated: "2026-08-17T02:33:16+05:30" --- # Quickstart > Install agent-qa with Node.js or Bun, connect an OpenAI, Anthropic, Gemini, or local LLM, prepare web and mobile runtimes, then inspect your first run end to end. 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 * 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 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. * 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 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. ```bash node --version npm --version ``` Skip this step when your repository already has a `package.json`. Otherwise, create one before installing agent-qa: ```bash npm init -y ``` Install `agent-qa` as a dev dependency so every teammate and CI job can run the same version. **Install agent-qa** ```bash # npm npm install -D agent-qa # pnpm pnpm add -D agent-qa # yarn yarn add -D agent-qa # bun bun add -d 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). **Install subscription auth support** ```bash # npm npm install -D @vostride/agent-qa-subscription-auth # pnpm pnpm add -D @vostride/agent-qa-subscription-auth # yarn yarn add -D @vostride/agent-qa-subscription-auth # bun bun add -d @vostride/agent-qa-subscription-auth ``` ## 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 Install browser runtimes for web tests. These agent-qa-managed browsers do not replace or interfere with browsers you already have installed. **Install browser support** ```bash # npm npx agent-qa install-browsers --all # pnpm pnpm exec agent-qa install-browsers --all # yarn yarn agent-qa install-browsers --all # bun bunx agent-qa install-browsers --all ``` ### Mobile drivers For Android or iOS tests, install the Appium runtime first: ```bash npm install -g appium appium --version ``` Then install the relevant mobile drivers: **Install mobile driver support** ```bash # npm npx agent-qa install-mobile-drivers --all # pnpm pnpm exec agent-qa install-mobile-drivers --all # yarn yarn agent-qa install-mobile-drivers --all # bun bunx agent-qa install-mobile-drivers --all ``` 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 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: ```bash docker --version docker info ``` 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 Run the init command to scaffold the config files, local settings, sample tests, and hook examples. **Initialize agent-qa** ```bash # npm npx agent-qa init # pnpm pnpm dlx agent-qa init # yarn yarn dlx agent-qa init # bun bunx agent-qa init ``` ### Verify the environment Run the doctor command after initialization to validate the local runtime pieces before your first test run. **Check agent-qa setup** ```bash # npm npx agent-qa doctor # pnpm pnpm exec agent-qa doctor # yarn yarn agent-qa doctor # bun bunx agent-qa doctor ``` 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. > The generated workspace includes project and local configuration, agent rules, tests, suites, hook definitions, and optional hook scripts. Exact sample names can vary by package version. Keep generated run artifacts out of commits unless your team intentionally stores them. ## Open the dashboard Start the local dashboard from the project root. **Open dashboard** ```bash # npm npx agent-qa dashboard --open # pnpm pnpm exec agent-qa dashboard --open # yarn yarn agent-qa dashboard --open # bun bunx agent-qa dashboard --open ``` 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 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 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: ```bash 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.