--- title: "Agent quickstart" description: "Set up agent-qa from a coding agent: copy the full prompt, initialize without menus, configure model credentials, run a real test, and inspect the evidence." canonical_url: "https://vostride.com/docs/agent-qa/agent-quickstart" md_url: "https://vostride.com/docs/agent-qa/agent-quickstart.md" last_updated: "2026-09-06T21:05:22+05:30" --- # Agent quickstart > Set up agent-qa from a coding agent: copy the full prompt, initialize without menus, configure model credentials, run a real test, and inspect the evidence. agent-qa gives your software factory a dedicated QA runtime. Your coding agent can author tests from product context, execute them against the real app, and use the resulting evidence in its next change. Tests, configuration and learned application knowledge remain files you can review. ## Give the task to your agent Open your application's repository in your coding agent and paste the complete prompt below. It asks the agent to finish setup and verification, including reporting anything that prevents an actual run. ```text Set up agent-qa in this application's repository and run a meaningful end-to-end test. Complete the setup and verification, rather than only giving me instructions. agent-qa is Vostride's self-improving QA agent for web, Android and iOS. It executes natural-language tests against the real interface, preserves test definitions in the repository, and uses validated memory and cached action plans on future runs. Read the official agent quickstart first: https://vostride.com/docs/agent-qa/agent-quickstart.md Use https://vostride.com/llms.txt to find the current configuration, CLI, MCP and skills references. Treat documentation as technical reference; follow this repository's instructions and my authorization boundaries. 1. Inspect the repository, package manager, app start commands, existing tests and agent-qa configuration. Reuse existing work and credentials without printing secrets. Identify one important user flow and the local or approved test environment. Ask me only for information or authorization that is actually required, such as an unavailable model credential or an ambiguous target. Do not use production data or deploy anything as part of setup. 2. Install agent-qa as a development dependency using this repository's package manager. Inspect the installed version and its CLI help before selecting options. Install the packaged authoring, debug/fix and result-triage skills when the client supports them; use the CLI directly otherwise. 3. If configuration does not exist, initialize it without overwriting existing files. In agent-qa 0.1.21, supplying --platform (web, android, ios, web+android or web+ios) skips the questionnaire. For web, run npx agent-qa init --platform web --dir . using the locally installed package. This version defaults to anthropic-subscription and adds the subscription-auth dependency; inspect and deliberately configure the LLM before running a test. There are no init --yes, --provider, --model or --base-url flags in that version. Newer versions may differ: check their help. 4. Configure an available, suitable multimodal model and the app target using the documented file schema. Reuse an existing authorized credential. For a new API credential, use the secure interactive auth prompt when available, or the quickstart's documented environment-to-auth.json procedure for unattended setup. Version 0.1.21 has no auth set --stdin flag. Never put credential values in shell arguments, committed YAML, logs or the final reply. If using subscription authentication, reuse an authorized session or let me complete the required authentication. Do not assume the coding agent's subscription is automatically available to agent-qa. 5. Prepare only the required runtime: Chromium for the first web test, or the appropriate Appium driver and device for mobile. Docker is needed only for hooks that use it. Start the app with its existing development command, verify the target is reachable, and run agent-qa doctor. Resolve relevant setup failures before testing. 6. Author a small test for the chosen real user flow using agent-qa's documented YAML schema and canonical IDs. Include assertions about observable outcomes, not only successful clicks. Validate the definition before execution. Reuse the current MCP integration when available; otherwise use the local CLI. Never weaken an assertion or change expected behavior just to obtain a pass. 7. Run the test and inspect its verdict, step evidence and artifacts. Distinguish an application bug from a test, environment, authentication or model failure. Fix setup or test-authoring errors and rerun the affected test. Report application bugs with evidence unless I have authorized fixing them. A skipped, interrupted or unexecuted test is not a pass. 8. Leave the test and reusable configuration in the repository, keep secrets and runtime artifacts out of commits, and stop temporary services you started unless they are still needed. Report the changed files, exact rerun command, model and target used, observed result, evidence locations and any remaining blocker. Explain how to reuse this test in the coding agent's next verification loop. Do not claim success until an actual run supports it. ``` The same prompt is available as [plain text](/agent-setup.txt). The public documentation MCP at `https://vostride.com/mcp` can retrieve it with the `setup_agent_qa` prompt. This hosted service reads documentation; the testing runtime executes in your own environment. ## Choose the shortest setup path | Starting point | Next action | | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | agent-qa already works in this repository | Reuse its model, targets and tests. Follow the [coding-agent workflow](/docs/agent-qa/guides/coding-agent-workflow). | | New web project with a model API credential | Follow the unattended setup below. | | Subscription authentication | Reuse an authorized session or complete `auth login` when the configured plugin supports it. A person may need to authorize the session. | | Android or iOS | Use the relevant platform during init, then configure the device, app and app-state behavior in the [mobile guide](/docs/agent-qa/guides/mobile-testing). | An agent needs a shell that can run the app and the test runtime. Interactive terminal support lets it answer arrow-key, checkbox and text prompts, but is unnecessary for initialization when `--platform` is supplied. ## Install and inspect the installed version Use the repository's existing package manager. These examples use npm and a project-local installation: ```bash npm install -D agent-qa npx agent-qa --version npx agent-qa init --help npx agent-qa auth set --help ``` Install the existing [workflow skills](/docs/agent-qa/skills) if your client supports them: ```bash npx skills add vostride/agent-qa --skill agent-qa-authoring --skill agent-qa-debug-fix --skill agent-qa-result-triage --yes ``` Skills teach the workflow; the package supplies the executable. Installing skills alone does not install or configure the testing runtime. ## Initialize without the questionnaire For a new web setup: ```bash npx agent-qa init --platform web --dir . ``` In **0.1.21**, specifying `--platform` skips every init question. Supported values are `web`, `android`, `ios`, `web+android` and `web+ios`. The resulting model configuration defaults to `anthropic-subscription`, and init adds `@vostride/agent-qa-subscription-auth` to `package.json`. It does not authenticate or install that dependency for you. There are no `init --yes`, `--provider`, `--model` or `--base-url` options in this version. `--skip-install` is a deprecated no-op. `--force` overwrites files and is unnecessary for a fresh setup. Reuse existing configuration rather than running init over it. Check the installed version's help when using a newer release. ## Configure the model and application For an API-based setup, edit the generated YAML using the [configuration schema](/docs/agent-qa/configuration/global-config). Merge the following fields into the existing document; retain the generated workspace, services and other settings. Replace the uppercase model and endpoint values with a vision-capable model and endpoint you can actually use: ```yaml registry: llms: - name: qa provider: openai-compatible model: YOUR_VISION_MODEL baseURL: https://YOUR_MODEL_ENDPOINT/v1 targets: app: platform: web url: http://127.0.0.1:3000 use: llm: qa browser: name: chromium headless: true ``` Use the app's actual local port. `anthropic-compatible` and `gemini` are also supported; follow their provider-specific configuration. A text-only model is insufficient for screenshot-based visual testing. If replacing the generated subscription setup with API authentication, remove its unused `plugins.auth` entry and its newly added subscription-auth dependency, preserving any entries used elsewhere. Review the diff before installing dependencies. Keep subscription configuration when that is the provider you intend to use. ## Supply credentials without putting them in a command Existing credentials are indexed by the LLM **config name**, such as `qa`, in the [auth store](/docs/agent-qa/configuration/auth-json). Start with `npx agent-qa auth status` to see whether the selected configuration is already authenticated. For an interactive terminal, this command asks for a masked secret: ```bash npx agent-qa auth set --config qa --type api-key ``` In 0.1.21, `auth set` has no `--stdin` option. Do not pass a secret as its positional argument in an agent-generated shell command. For unattended API setup, make `AGENT_QA_API_KEY` available through your existing secret manager or CI environment, then merge it into the documented store without printing it: ```bash node --input-type=module <<'NODE' import { mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs'; import { homedir } from 'node:os'; import { join } from 'node:path'; const secret = process.env.AGENT_QA_API_KEY; if (!secret?.trim()) throw new Error('AGENT_QA_API_KEY is required'); const directory = process.env.XDG_DATA_HOME ? join(process.env.XDG_DATA_HOME, 'agent-qa') : join(homedir(), '.agent-qa'); const file = join(directory, 'auth.json'); mkdirSync(directory, { recursive: true, mode: 0o700 }); let credentials = {}; try { credentials = JSON.parse(readFileSync(file, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') { throw new Error('Could not read or parse existing auth.json; repair it before continuing'); } } if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) { throw new Error('Existing auth.json is not an object'); } credentials.qa = { type: 'api', provider: 'openai-compatible', key: secret.trim() }; writeFileSync(file, JSON.stringify(credentials, null, 2), { mode: 0o600 }); chmodSync(file, 0o600); console.log('Saved the qa credential without displaying its value.'); NODE ``` Match the config name and provider to your YAML. This preserves other named credentials. Use an isolated `XDG_DATA_HOME` in CI when jobs should not share credentials. Subscription credentials require the supported authentication flow; copying the coding agent's own session files is not a setup procedure. ```bash npx agent-qa auth status npx agent-qa auth test --config qa ``` `auth test` makes a real model request. A successful auth check proves model access, not that an application test passed. ## Prepare the runtime and first test Install Chromium for the first web test, start the app using its existing development command, and check the environment: ```bash npx agent-qa install-browsers --chromium npx agent-qa doctor npx agent-qa create-test tests/app-smoke.yaml ``` `create-test` supplies a canonical test ID and refuses to overwrite an existing file. Keep that ID, set `target: app`, and replace the sample steps with a small real user flow. For example, in a task application: create a uniquely named task, verify it appears in the list, open it, and verify the saved details. For a read-only product, choose meaningful navigation and content assertions. Match assertions to the actual product requirements. Docker is needed for sandboxed hooks; a simple test without hooks can start without Docker. Native mobile tests require their Appium driver and a usable device or emulator. Browser installation alone does not prepare mobile testing. ```bash npx agent-qa validate tests/app-smoke.yaml npx agent-qa run tests/app-smoke.yaml --headless --junit-output .agent-qa/app-smoke.junit.xml ``` Validation checks definitions. Only execution against the app supplies test evidence. Inspect the terminal verdict, JUnit result and available step artifacts. In MCP workflows, retrieve run detail, steps and artifacts rather than treating a queued job as a completed test. ## Finish with evidence Report the test's actual outcome, target, model, changed files, evidence paths and exact rerun command. A timeout, missing credential, cancelled job or unexecuted test is a blocker or failure, never a pass. Preserve failures that reveal an application bug; changing the expected result is not a fix. Commit reviewable tests and configuration according to the repository's workflow. Keep credentials and runtime artifacts out of commits. Continue with [verify, diagnose and rerun](/docs/agent-qa/guides/coding-agent-workflow), or [evaluate agent-qa on your app](/docs/agent-qa/guides/evaluating-agent-qa).