--- title: Global Config description: Configure workspace discovery, services, registries, plugins, analytics, and default run behavior in agent-qa.config.yaml. --- `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 [#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 [#workspace] The `workspace` block is required. All paths are resolved from the directory that contains `agent-qa.config.yaml`. ### workspace.testMatch [#workspacetestmatch] ```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 [#workspacesuitematch] ```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 [#workspacetestpathignore] ```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 [#workspacehooksfile] ```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 [#workspaceagentrules] ```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 [#workspaceenvfile] ```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 [#workspacesecretsfile] ```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 [#servicesdashboard] Dashboard service settings are optional. They affect local dashboard state and artifact locations. ### services.dashboard.port [#servicesdashboardport] ```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 [#servicesdashboarddbpath] ```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 [#servicesdashboardartifactsdir] ```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 [#servicesmcp] MCP hosts are intentionally local-only. Valid HTTP hosts are `localhost`, `127.0.0.1`, and `::1`. ### services.mcp.enabled [#servicesmcpenabled] ```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 [#servicesmcptransport] ```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 [#servicesmcphost] ```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 [#servicesmcpport] ```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 [#servicesmcppath] ```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 [#servicescache] ### services.cache.dir [#servicescachedir] ```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 [#servicescachettl] ```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 [#servicesauthstate] ### services.authState.dir [#servicesauthstatedir] ```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 [#serviceslogging] ### services.logging.level [#serviceslogginglevel] ```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 [#servicesrecording] ### services.recording.enabled [#servicesrecordingenabled] ```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 [#servicesaccessibility] ### services.accessibility.enabled [#servicesaccessibilityenabled] ```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 [#servicesaccessibilitystandard] ```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 [#servicesaccessibilityrunafter] ```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 [#servicesaccessibilityfailonviolation] ```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 [#servicesaccessibilitydisablerules] ```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 [#servicesaccessibilityexclude] ```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 [#servicesmemory] ### services.memory.enabled [#servicesmemoryenabled] ```yaml services: memory: enabled: true ``` Description: Enables runtime memory injection. Possible values: `true` or `false`. Required: no. Default: `true`. ### services.memory.provider [#servicesmemoryprovider] ```yaml services: memory: provider: local ``` Description: Memory storage provider. Possible values: `local`. Required: no. Default: `local`. ### services.memory.dir [#servicesmemorydir] ```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 [#servicesmemorymintrust] ```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 [#servicesmemorymaxinjections] ```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 [#servicesmemorycuratorenabled] ```yaml services: memory: curatorEnabled: true ``` Description: Enables the memory curator after runs. Possible values: `true` or `false`. Required: no. Default: `true`. ### services.memory.curatorLockTimeout [#servicesmemorycuratorlocktimeout] ```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 [#servicesmemorytrustconfirmdelta] ```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 [#servicesmemorytrustcontradictdelta] ```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 [#servicesmemoryablationenabled] ```yaml services: memory: ablationEnabled: true ``` Description: Enables memory ablation behavior. Possible values: `true` or `false`. Required: no. Default: `true`. ### services.memory.circuitBreakerEnabled [#servicesmemorycircuitbreakerenabled] ```yaml services: memory: circuitBreakerEnabled: true ``` Description: Enables the memory circuit breaker. Possible values: `true` or `false`. Required: no. Default: `true`. ### services.memory.circuitBreakerWindowSize [#servicesmemorycircuitbreakerwindowsize] ```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 [#servicesmemorycircuitbreakerbaselinesize] ```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 [#servicesmemorycircuitbreakerthreshold] ```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 [#registryllms] Each LLM entry names a model configuration that `use.llm`, tests, suites, and auth storage can reference. ### registry.llms.name [#registryllmsname] ```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 [#registryllmsprovider] ```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 [#registryllmsmodel] ```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 [#registryllmsbaseurl] ```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 [#registryllmsproviderheaders] ```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 [#registryllmsscreenshotsize] ```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 [#registryllmseffectiveresolution] ```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 [#registryllmscontextwindow] ```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 [#registrytargets] Targets are the named apps under test. Web targets are the common path for most teams. ### registry.targets.product [#registrytargetsproduct] ```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 [#registrytargetsplatform] ```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 [#registrytargetsurl] ```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 [#registrytargetsbundleid] ```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 [#registrytargetsapppackage] ```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 [#registrytargetsappactivity] ```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 [#registrytargetsapppath] ```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 [#registrytargetsappbrowserstack] ```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 [#registrydevices] Device profiles are reusable mobile device references. Web tests normally do not need this block. ### registry.devices.platform [#registrydevicesplatform] ```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 [#registrydevicestransport] ```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 [#registrydevicesmatch] ```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 [#registryproviders] ### registry.providers [#registryproviders-1] ```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] ### plugins.auth.package [#pluginsauthpackage] ```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 [#pluginsauthpath] ```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] `use` contains defaults that cascade into suite and test runs. CLI flags and test-level `use` values can override them. ### use.browser.name [#usebrowsername] ```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 [#usebrowserheadless] ```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 [#usebrowserviewportwidth] ```yaml use: browser: viewport: width: 1280 ``` Description: Browser viewport width. Possible values: number. Required: no. Default: not set by schema. ### use.browser.viewport.height [#usebrowserviewportheight] ```yaml use: browser: viewport: height: 720 ``` Description: Browser viewport height. Possible values: number. Required: no. Default: not set by schema. ### use.mobile.appState [#usemobileappstate] ```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 [#usetimeoutstep] ```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 [#usetimeouttest] ```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 [#usetimeoutnavigation] ```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 [#usehealingmaxattempts] ```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 [#useplannermaxsubactions] ```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 [#useplannerpreviousstepcount] ```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 [#uselogcaptureconsole] ```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 [#uselogcapturenetwork] ```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 [#usecache] ```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 [#usellm] ```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 [#useparallel] ```yaml use: parallel: false ``` Description: Allows parallel execution where supported. Possible values: `true` or `false`. Required: no. Default: not set by schema. ## analytics [#analytics] ### analytics.privacy [#analyticsprivacy] ```yaml analytics: privacy: true ``` Description: Privacy flag for analytics behavior. Possible values: `true`. Required: no. Default: not set. ### analytics.passRateScope.attributes [#analyticspassratescopeattributes] ```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-overrides] Environment variables can override selected global config keys at load time. ### AGENT\_QA\_DASHBOARD\_PORT [#agent_qa_dashboard_port] ```bash AGENT_QA_DASHBOARD_PORT=3110 ``` Overrides: `services.dashboard.port`. ### AGENT\_QA\_MCP\_PORT [#agent_qa_mcp_port] ```bash AGENT_QA_MCP_PORT=3481 ``` Overrides: `services.mcp.port`. ### AGENT\_QA\_CACHE\_DIR [#agent_qa_cache_dir] ```bash AGENT_QA_CACHE_DIR=.agent-qa/cache ``` Overrides: `services.cache.dir`. ### AGENT\_QA\_CACHE\_TTL [#agent_qa_cache_ttl] ```bash AGENT_QA_CACHE_TTL=7d ``` Overrides: `services.cache.ttl`. ### AGENT\_QA\_LOG\_LEVEL [#agent_qa_log_level] ```bash AGENT_QA_LOG_LEVEL=debug ``` Overrides: `services.logging.level`. ### AGENT\_QA\_HEADLESS [#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.