---
title: "Global Config"
description: "agent-qa.config.yaml reference by key: workspace discovery, dashboard and MCP services, LLM and target registries, devices, auth plugins, analytics, and defaults."
canonical_url: "https://vostride.com/docs/agent-qa/configuration/global-config"
md_url: "https://vostride.com/docs/agent-qa/configuration/global-config.md"
last_updated: "2026-08-17T02:33:16+05:30"
---

# Global Config

> agent-qa.config.yaml reference by key: workspace discovery, dashboard and MCP services, LLM and target registries, devices, auth plugins, analytics, and defaults.

`agent-qa.config.yaml` is the project-wide source of truth. It tells agent-qa where to find tests, suites, hooks, variables, secrets, rules, and output; which browser targets and LLM configs exist; and which defaults apply before a suite, test, dashboard action, or CLI flag overrides them.

This page is organized by config key so each option has a stable heading URL you can share in review comments.

## Complete web example
This example uses a web app running locally. Native mobile fields are only included where the current schema expects a mobile app-state default.

```yaml
workspace:
  testMatch:
    - tests/**/*.yaml
  suiteMatch:
    - suites/**/*.suite.yaml
  testPathIgnore:
    - tests/archive/**/*.yaml
  hooksFile: hooks.yaml
  agentRules: ./agent-rules.md
  envFile: .env
  secretsFile: .env.secrets.local

services:
  dashboard:
    port: 3110
    dbPath: .agent-qa/dashboard.sqlite
    artifactsDir: .agent-qa/artifacts
  mcp:
    enabled: true
    transport: http
    host: 127.0.0.1
    port: 3481
    path: /mcp
  cache:
    dir: .agent-qa/cache
    ttl: 7d
  authState:
    dir: .agent-qa/auth-states
  logging:
    level: warn
  recording:
    enabled: true
  accessibility:
    enabled: true
    standard: wcag2aa
    runAfter: navigation
    failOnViolation: false
  memory:
    enabled: true
    provider: local
    dir: agent-qa-memory

registry:
  llms:
    - name: codex
      provider: openai-subscription
      model: gpt-5.5
      screenshotSize: 50kb
      effectiveResolution: 500
  targets:
    issue-tracker-web:
      platform: web
      product: issue-tracker
      url: http://localhost:3000

plugins:
  auth:
    - package: "@vostride/agent-qa-subscription-auth"

use:
  browser:
    name: chromium
    headless: true
    viewport:
      width: 1280
      height: 720
  mobile:
    appState: preserve
  timeout:
    step: 5m
    test: 45m
    navigation: 90s
  healing:
    maxAttempts: 3
  planner:
    maxSubActions: 12
    previousStepCount: 6
  logCapture:
    console: true
    network: true
  cache: true
  parallel: false
  llm: codex

analytics:
  privacy: true
  passRateScope:
    attributes:
      branch:
        regex: "^(main|release/.+)$"
```

## workspace
The `workspace` block is required. All paths are resolved from the directory that contains `agent-qa.config.yaml`.

### workspace.testMatch
```yaml
workspace:
  testMatch:
    - tests/**/*.yaml
```

Description: Glob patterns used by test discovery in the CLI and dashboard.

Possible values: one or more non-empty glob strings.

Required: yes.

Default: none. The config must provide at least one pattern.

### workspace.suiteMatch
```yaml
workspace:
  suiteMatch:
    - suites/**/*.suite.yaml
```

Description: Glob patterns used by suite discovery.

Possible values: one or more non-empty glob strings.

Required: yes.

Default: none. The config must provide at least one pattern.

### workspace.testPathIgnore
```yaml
workspace:
  testPathIgnore:
    - tests/archive/**/*.yaml
```

Description: Optional glob patterns excluded from test and suite discovery.

Possible values: zero or more glob strings.

Required: no.

Default: not set.

### workspace.hooksFile
```yaml
workspace:
  hooksFile: hooks.yaml
```

Description: Path to the hook registry file.

Possible values: any non-empty workspace-relative path.

Required: yes.

Default: none.

### workspace.agentRules
```yaml
workspace:
  agentRules: ./agent-rules.md
```

Description: Path to project-specific QA agent instructions.

Possible values: any non-empty workspace-relative path.

Required: yes.

Default: none.

### workspace.envFile
```yaml
workspace:
  envFile: .env
```

Description: Path to dotenv-style non-secret variables used with `{{env:NAME}}`.

Possible values: any non-empty workspace-relative path.

Required: yes.

Default: none. The referenced file must exist, even if it is empty.

### workspace.secretsFile
```yaml
workspace:
  secretsFile: .env.secrets.local
```

Description: Path to dotenv-style secrets used with `{{secret:NAME}}`.

Possible values: any non-empty workspace-relative path.

Required: yes.

Default: none. Keep this file out of git.

## services.dashboard
Dashboard service settings are optional. They affect local dashboard state and artifact locations.

### services.dashboard.port
```yaml
services:
  dashboard:
    port: 3110
```

Description: Port used by the local dashboard server.

Possible values: a number.

Required: no.

Default: not set by schema.

### services.dashboard.dbPath
```yaml
services:
  dashboard:
    dbPath: .agent-qa/dashboard.sqlite
```

Description: SQLite path for dashboard state.

Possible values: a workspace-relative or process-resolved path string.

Required: no.

Default: not set by schema.

### services.dashboard.artifactsDir
```yaml
services:
  dashboard:
    artifactsDir: .agent-qa/artifacts
```

Description: Directory used by the dashboard to read and write run artifacts.

Possible values: a path string.

Required: no.

Default: not set by schema.

## services.mcp
MCP hosts are intentionally local-only. Valid HTTP hosts are `localhost`, `127.0.0.1`, and `::1`.

### services.mcp.enabled
```yaml
services:
  mcp:
    enabled: true
```

Description: Enables the local MCP service.

Possible values: `true` or `false`.

Required: no.

Default: not set by schema.

### services.mcp.transport
```yaml
services:
  mcp:
    transport: http
```

Description: Chooses how the MCP service is exposed.

Possible values: `http` or `stdio`.

Required: no.

Default: not set by schema.

### services.mcp.host
```yaml
services:
  mcp:
    host: 127.0.0.1
```

Description: Loopback host used for HTTP MCP.

Possible values: `localhost`, `127.0.0.1`, or `::1`.

Required: no.

Default: not set by schema.

### services.mcp.port
```yaml
services:
  mcp:
    port: 3481
```

Description: Port used by HTTP MCP.

Possible values: an integer from 1 to 65535.

Required: no.

Default: not set by schema.

### services.mcp.path
```yaml
services:
  mcp:
    path: /mcp
```

Description: HTTP path for MCP requests.

Possible values: a non-empty string starting with `/`.

Required: no.

Default: not set by schema.

## services.cache
### services.cache.dir
```yaml
services:
  cache:
    dir: .agent-qa/cache
```

Description: Directory for action cache data.

Possible values: a path string.

Required: yes when `services.cache` is present.

Default: not set by schema.

### services.cache.ttl
```yaml
services:
  cache:
    ttl: 7d
```

Description: Time to keep cache entries.

Possible values: duration strings such as `30s`, `5m`, `1h`, and `7d`.

Required: yes when `services.cache` is present.

Default: not set by schema.

## services.authState
### services.authState.dir
```yaml
services:
  authState:
    dir: .agent-qa/auth-states
```

Description: Directory for named web auth-state payloads and metadata. Keep this directory out of git.

Possible values: any non-empty path string.

Required: yes when `services.authState` is present.

Default: `.agent-qa/auth-states` when auth state is resolved without an explicit directory.

## services.logging
### services.logging.level
```yaml
services:
  logging:
    level: warn
```

Description: Default log level. CLI `--log-level`, `--verbose`, and `--quiet` can override it.

Possible values: `silent`, `error`, `warn`, `info`, or `debug`.

Required: yes when `services.logging` is present.

Default: not set by schema.

## services.recording
### services.recording.enabled
```yaml
services:
  recording:
    enabled: true
```

Description: Enables video recording defaults. CLI `--record` can also enable recording for a run.

Possible values: `true` or `false`.

Required: no.

Default: not set by schema.

## services.accessibility
### services.accessibility.enabled
```yaml
services:
  accessibility:
    enabled: true
```

Description: Enables accessibility checks for web runs.

Possible values: `true` or `false`.

Required: yes when `services.accessibility` is present.

Default: not set by schema.

### services.accessibility.standard
```yaml
services:
  accessibility:
    standard: wcag2aa
```

Description: Accessibility standard used by the checker.

Possible values: `wcag2a`, `wcag2aa`, or `wcag2aaa`.

Required: no.

Default: not set by schema.

### services.accessibility.runAfter
```yaml
services:
  accessibility:
    runAfter: navigation
```

Description: Controls when accessibility scans run during a web test.

Possible values: `every-step`, `navigation`, or `test-end`.

Required: no.

Default: not set by schema.

### services.accessibility.failOnViolation
```yaml
services:
  accessibility:
    failOnViolation: false
```

Description: Fails the run when accessibility violations are found.

Possible values: `true` or `false`.

Required: no.

Default: not set by schema.

### services.accessibility.disableRules
```yaml
services:
  accessibility:
    disableRules:
      - color-contrast
```

Description: Rule IDs to disable.

Possible values: zero or more rule ID strings.

Required: no.

Default: not set.

### services.accessibility.exclude
```yaml
services:
  accessibility:
    exclude:
      - "[data-test-preview]"
```

Description: Selectors excluded from accessibility scanning.

Possible values: zero or more selector strings.

Required: no.

Default: not set.

## services.memory
### services.memory.enabled
```yaml
services:
  memory:
    enabled: true
```

Description: Enables runtime memory injection.

Possible values: `true` or `false`.

Required: no.

Default: `true`.

### services.memory.provider
```yaml
services:
  memory:
    provider: local
```

Description: Memory storage provider.

Possible values: `local`.

Required: no.

Default: `local`.

### services.memory.dir
```yaml
services:
  memory:
    dir: agent-qa-memory
```

Description: Directory used by local memory.

Possible values: a non-empty path string.

Required: no.

Default: the built-in local memory directory.

### services.memory.minTrust
```yaml
services:
  memory:
    minTrust: 0.3
```

Description: Minimum trust score required before memory is injected into a step.

Possible values: a number from 0 to 1.

Required: no.

Default: `0.3`.

### services.memory.maxInjections
```yaml
services:
  memory:
    maxInjections: 3
```

Description: Maximum number of memory entries injected into a step.

Possible values: an integer greater than or equal to 0.

Required: no.

Default: `3`.

### services.memory.curatorEnabled
```yaml
services:
  memory:
    curatorEnabled: true
```

Description: Enables the memory curator after runs.

Possible values: `true` or `false`.

Required: no.

Default: `true`.

### services.memory.curatorLockTimeout
```yaml
services:
  memory:
    curatorLockTimeout: 120000
```

Description: Curator lock timeout in milliseconds.

Possible values: an integer of at least 1000.

Required: no.

Default: `120000`.

### services.memory.trustConfirmDelta
```yaml
services:
  memory:
    trustConfirmDelta: 0.05
```

Description: Trust increase applied when memory is confirmed.

Possible values: a number from 0 to 1.

Required: no.

Default: `0.05`.

### services.memory.trustContradictDelta
```yaml
services:
  memory:
    trustContradictDelta: 0.10
```

Description: Trust decrease applied when memory is contradicted.

Possible values: a number from 0 to 1.

Required: no.

Default: `0.10`.

### services.memory.ablationEnabled
```yaml
services:
  memory:
    ablationEnabled: true
```

Description: Enables memory ablation behavior.

Possible values: `true` or `false`.

Required: no.

Default: `true`.

### services.memory.circuitBreakerEnabled
```yaml
services:
  memory:
    circuitBreakerEnabled: true
```

Description: Enables the memory circuit breaker.

Possible values: `true` or `false`.

Required: no.

Default: `true`.

### services.memory.circuitBreakerWindowSize
```yaml
services:
  memory:
    circuitBreakerWindowSize: 20
```

Description: Window size for memory circuit checks.

Possible values: an integer of at least 5.

Required: no.

Default: `20`.

### services.memory.circuitBreakerBaselineSize
```yaml
services:
  memory:
    circuitBreakerBaselineSize: 3
```

Description: Baseline sample size for memory circuit checks.

Possible values: an integer of at least 2.

Required: no.

Default: `3`.

### services.memory.circuitBreakerThreshold
```yaml
services:
  memory:
    circuitBreakerThreshold: 0.15
```

Description: Failure threshold for the memory circuit breaker.

Possible values: a number from 0 to 1.

Required: no.

Default: `0.15`.

## registry.llms
Each LLM entry names a model configuration that `use.llm`, tests, suites, and auth storage can reference.

### registry.llms.name
```yaml
registry:
  llms:
    - name: codex
```

Description: Stable config name for this LLM.

Possible values: lowercase alphanumeric names with hyphens, starting with an alphanumeric character.

Required: yes for each LLM entry.

Default: none.

### registry.llms.provider
```yaml
registry:
  llms:
    - name: codex
      provider: openai-subscription
```

Description: Provider ID used to resolve model access.

Possible values: built-in provider modes such as `openai-compatible`, `anthropic-compatible`, `openai-subscription`, `anthropic-subscription`, and `gemini`, plus provider IDs added by auth plugins.

Required: yes for each LLM entry.

Default: none.

### registry.llms.model
```yaml
registry:
  llms:
    - name: codex
      provider: openai-subscription
      model: gpt-5.5
```

Description: Provider model name.

Possible values: any provider-supported model string.

Required: yes for each LLM entry.

Default: none.

### registry.llms.baseURL
```yaml
registry:
  llms:
    - name: local-openai
      provider: openai-compatible
      model: qwen2.5-vl
      baseURL: http://localhost:11434/v1
```

Description: Base URL for compatible providers.

Possible values: a URL string.

Required: yes for `openai-compatible` and `anthropic-compatible` providers.

Default: not set.

### registry.llms.providerHeaders
```yaml
registry:
  llms:
    - name: claude-compatible
      provider: anthropic-compatible
      model: claude-sonnet-4-5
      baseURL: https://api.anthropic.com
      providerHeaders:
        anthropic-beta: token-efficient-tools-2025-02-19
```

Description: Extra provider headers for Anthropic-compatible requests. Header names that look like auth headers are rejected.

Possible values: string-to-string header map.

Required: no.

Default: not set.

### registry.llms.screenshotSize
```yaml
registry:
  llms:
    - name: codex
      provider: openai-subscription
      model: gpt-5.5
      screenshotSize: 50kb
```

Description: Optional screenshot compression target for this model config.

Possible values: size strings such as `50kb`, `256k`, and `1mb`.

Required: no.

Default: not set.

### registry.llms.effectiveResolution
```yaml
registry:
  llms:
    - name: codex
      provider: openai-subscription
      model: gpt-5.5
      effectiveResolution: 500
```

Description: Optional positive integer describing effective image resolution.

Possible values: positive integers.

Required: no.

Default: not set.

### registry.llms.contextWindow
```yaml
registry:
  llms:
    - name: codex
      provider: openai-subscription
      model: gpt-5.5
      contextWindow: 1mb
```

Description: Optional context window hint for a named LLM config.

Possible values: size strings such as `256kb`, `1mb`, or `2mb`.

Required: no.

Default: not set.

## registry.targets
Targets are the named apps under test. Web targets are the common path for most teams.

### registry.targets.product
```yaml
registry:
  targets:
    issue-tracker-web:
      product: issue-tracker
```

Description: Optional product label for the target.

Possible values: strings that do not contain `..`, path separators, or null bytes.

Required: no.

Default: not set.

### registry.targets.platform
```yaml
registry:
  targets:
    issue-tracker-web:
      platform: web
```

Description: Target platform.

Possible values: `web`, `android`, or `ios`.

Required: yes for each target.

Default: none.

### registry.targets.url
```yaml
registry:
  targets:
    issue-tracker-web:
      platform: web
      url: http://localhost:3000
```

Description: Start URL for a web target.

Possible values: a URL string.

Required: yes when `platform` is `web`.

Default: none.

### registry.targets.bundleId
```yaml
registry:
  targets:
    ios-release:
      platform: ios
      bundleId: com.company.issuetracker
```

Description: iOS bundle identifier for native iOS targets.

Possible values: string.

Required: no.

Default: not set.

### registry.targets.appPackage
```yaml
registry:
  targets:
    android-release:
      platform: android
      appPackage: com.company.issuetracker
```

Description: Android package name for native Android targets.

Possible values: string.

Required: no.

Default: not set.

### registry.targets.appActivity
```yaml
registry:
  targets:
    android-release:
      platform: android
      appActivity: .MainActivity
```

Description: Android launch activity for native Android targets.

Possible values: string.

Required: no.

Default: not set.

### registry.targets.app.path
```yaml
registry:
  targets:
    android-release:
      platform: android
      app:
        path: apps/android/release.apk
```

Description: Portable app artifact path for native targets. Absolute paths are rejected; local machine overrides belong in `agent-qa.local.yaml`.

Possible values: relative path string.

Required: no.

Default: not set.

### registry.targets.app.browserstack
```yaml
registry:
  targets:
    android-release:
      platform: android
      app:
        browserstack: bs://uploaded-app-id
```

Description: BrowserStack app reference for native targets.

Possible values: BrowserStack app reference or relative value.

Required: no.

Default: not set.

## registry.devices
Device profiles are reusable mobile device references. Web tests normally do not need this block.

### registry.devices.platform
```yaml
registry:
  devices:
    android-local:
      platform: android
```

Description: Device platform.

Possible values: `android` or `ios`.

Required: yes for each device profile.

Default: none.

### registry.devices.transport
```yaml
registry:
  devices:
    android-local:
      platform: android
      transport: local
```

Description: Device transport.

Possible values: `local` or `browserstack`.

Required: yes for each device profile.

Default: none.

### registry.devices.match
```yaml
registry:
  devices:
    android-local:
      platform: android
      transport: local
      match:
        appPackage: com.company.issuetracker
```

Description: Provider-specific match fields. Local Android permits `avd`, `serial`, `appPackage`, `appActivity`, `automationName`, `browserName`, and `platformVersion`. Local iOS permits `udid`, `bundleId`, `automationName`, and `platformVersion`.

Possible values: object with fields accepted by the chosen platform and transport.

Required: no.

Default: empty object.

## registry.providers
### registry.providers
```yaml
registry:
  providers:
    browserstack:
      project: issue-tracker-web
```

Description: Provider-specific objects for integrations that need named settings. Keep secrets in `agent-qa.local.yaml`, environment variables, or auth storage.

Possible values: provider-name keys with provider-specific objects.

Required: no.

Default: not set.

## plugins
### plugins.auth.package
```yaml
plugins:
  auth:
    - package: "@vostride/agent-qa-subscription-auth"
```

Description: Auth plugin package loaded relative to the config file.

Possible values: package import string.

Required: either `package` or `path` is required for each auth plugin entry.

Default: no auth plugins.

### plugins.auth.path
```yaml
plugins:
  auth:
    - path: ./tools/agent-qa-auth-plugin.mjs
```

Description: Local auth plugin module.

Possible values: path string.

Required: either `package` or `path` is required for each auth plugin entry.

Default: no auth plugins.

## use
`use` contains defaults that cascade into suite and test runs. CLI flags and test-level `use` values can override them.

### use.browser.name
```yaml
use:
  browser:
    name: chromium
```

Description: Browser engine used for web tests.

Possible values: `chromium`, `firefox`, or `webkit`.

Required: yes when `use.browser` is present.

Default: not set by schema.

### use.browser.headless
```yaml
use:
  browser:
    headless: true
```

Description: Runs web tests without a visible browser window.

Possible values: `true` or `false`.

Required: yes when `use.browser` is present.

Default: not set by schema.

### use.browser.viewport.width
```yaml
use:
  browser:
    viewport:
      width: 1280
```

Description: Browser viewport width.

Possible values: number.

Required: no.

Default: not set by schema.

### use.browser.viewport.height
```yaml
use:
  browser:
    viewport:
      height: 720
```

Description: Browser viewport height.

Possible values: number.

Required: no.

Default: not set by schema.

### use.mobile.appState
```yaml
use:
  mobile:
    appState: preserve
```

Description: Native mobile app-state behavior. Web tests do not use this value, but the current global config schema validates it when `use` is present.

Possible values: `preserve` or `reset`.

Required: yes when `use.mobile` is present.

Default: none.

### use.timeout.step
```yaml
use:
  timeout:
    step: 5m
```

Description: Default timeout for one test step.

Possible values: duration strings such as `30s`, `5m`, and `1h`.

Required: yes when `use.timeout` is present.

Default: not set by schema.

### use.timeout.test
```yaml
use:
  timeout:
    test: 45m
```

Description: Default timeout for the whole test.

Possible values: duration strings.

Required: yes when `use.timeout` is present.

Default: not set by schema.

### use.timeout.navigation
```yaml
use:
  timeout:
    navigation: 90s
```

Description: Default timeout for navigation actions.

Possible values: duration strings.

Required: yes when `use.timeout` is present.

Default: not set by schema.

### use.healing.maxAttempts
```yaml
use:
  healing:
    maxAttempts: 3
```

Description: Default self-healing retry budget.

Possible values: number.

Required: yes when `use.healing` is present.

Default: not set by schema.

### use.planner.maxSubActions
```yaml
use:
  planner:
    maxSubActions: 12
```

Description: Planner sub-action budget per step.

Possible values: number.

Required: yes when `use.planner` is present.

Default: not set by schema.

### use.planner.previousStepCount
```yaml
use:
  planner:
    previousStepCount: 6
```

Description: Number of previous steps included as context.

Possible values: number.

Required: yes when `use.planner` is present.

Default: not set by schema.

### use.logCapture.console
```yaml
use:
  logCapture:
    console: true
```

Description: Captures browser console logs.

Possible values: `true` or `false`.

Required: yes when `use.logCapture` is present.

Default: not set by schema.

### use.logCapture.network
```yaml
use:
  logCapture:
    network: true
```

Description: Captures browser network logs.

Possible values: `true` or `false`.

Required: yes when `use.logCapture` is present.

Default: not set by schema.

### use.cache
```yaml
use:
  cache: true
```

Description: Enables action cache by default. CLI `--no-cache` disables it for one run.

Possible values: `true` or `false`.

Required: no.

Default: not set by schema.

### use.llm
```yaml
use:
  llm: codex
```

Description: Default LLM config name.

Possible values: the `name` of an entry in `registry.llms`.

Required: no.

Default: not set by schema.

### use.parallel
```yaml
use:
  parallel: false
```

Description: Allows parallel execution where supported.

Possible values: `true` or `false`.

Required: no.

Default: not set by schema.

## analytics
### analytics.privacy
```yaml
analytics:
  privacy: true
```

Description: Privacy flag for analytics behavior.

Possible values: `true`.

Required: no.

Default: not set.

### analytics.passRateScope.attributes
```yaml
analytics:
  passRateScope:
    attributes:
      branch:
        regex: "^(main|release/.+)$"
```

Description: Attribute filters used for pass-rate scoping.

Possible values: string values or objects with a non-empty `regex` string.

Required: no.

Default: not set.

## Environment overrides
Environment variables can override selected global config keys at load time.

### AGENT\_QA\_DASHBOARD\_PORT
```bash
AGENT_QA_DASHBOARD_PORT=3110
```

Overrides: `services.dashboard.port`.

### AGENT\_QA\_MCP\_PORT
```bash
AGENT_QA_MCP_PORT=3481
```

Overrides: `services.mcp.port`.

### AGENT\_QA\_CACHE\_DIR
```bash
AGENT_QA_CACHE_DIR=.agent-qa/cache
```

Overrides: `services.cache.dir`.

### AGENT\_QA\_CACHE\_TTL
```bash
AGENT_QA_CACHE_TTL=7d
```

Overrides: `services.cache.ttl`.

### AGENT\_QA\_LOG\_LEVEL
```bash
AGENT_QA_LOG_LEVEL=debug
```

Overrides: `services.logging.level`.

### AGENT\_QA\_HEADLESS
```bash
AGENT_QA_HEADLESS=false
```

Overrides: `use.browser.headless`.

Use `agent-qa run --config-debug` when you want to inspect the resolved config with source attribution.