Global Config
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
This example uses a web app running locally. Native mobile fields are only included where the current schema expects a mobile app-state default.
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
workspace:
testMatch:
- tests/**/*.yamlDescription: 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
workspace:
suiteMatch:
- suites/**/*.suite.yamlDescription: 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
workspace:
testPathIgnore:
- tests/archive/**/*.yamlDescription: Optional glob patterns excluded from test and suite discovery.
Possible values: zero or more glob strings.
Required: no.
Default: not set.
workspace.hooksFile
workspace:
hooksFile: hooks.yamlDescription: Path to the hook registry file.
Possible values: any non-empty workspace-relative path.
Required: yes.
Default: none.
workspace.agentRules
workspace:
agentRules: ./agent-rules.mdDescription: Path to project-specific QA agent instructions.
Possible values: any non-empty workspace-relative path.
Required: yes.
Default: none.
workspace.envFile
workspace:
envFile: .envDescription: 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
workspace:
secretsFile: .env.secrets.localDescription: 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
services:
dashboard:
port: 3110Description: Port used by the local dashboard server.
Possible values: a number.
Required: no.
Default: not set by schema.
services.dashboard.dbPath
services:
dashboard:
dbPath: .agent-qa/dashboard.sqliteDescription: 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
services:
dashboard:
artifactsDir: .agent-qa/artifactsDescription: 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
services:
mcp:
enabled: trueDescription: Enables the local MCP service.
Possible values: true or false.
Required: no.
Default: not set by schema.
services.mcp.transport
services:
mcp:
transport: httpDescription: Chooses how the MCP service is exposed.
Possible values: http or stdio.
Required: no.
Default: not set by schema.
services.mcp.host
services:
mcp:
host: 127.0.0.1Description: 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
services:
mcp:
port: 3481Description: Port used by HTTP MCP.
Possible values: an integer from 1 to 65535.
Required: no.
Default: not set by schema.
services.mcp.path
services:
mcp:
path: /mcpDescription: 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
services:
cache:
dir: .agent-qa/cacheDescription: 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
services:
cache:
ttl: 7dDescription: 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
services:
authState:
dir: .agent-qa/auth-statesDescription: 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
services:
logging:
level: warnDescription: 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
services:
recording:
enabled: trueDescription: 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
services:
accessibility:
enabled: trueDescription: 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
services:
accessibility:
standard: wcag2aaDescription: Accessibility standard used by the checker.
Possible values: wcag2a, wcag2aa, or wcag2aaa.
Required: no.
Default: not set by schema.
services.accessibility.runAfter
services:
accessibility:
runAfter: navigationDescription: 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
services:
accessibility:
failOnViolation: falseDescription: Fails the run when accessibility violations are found.
Possible values: true or false.
Required: no.
Default: not set by schema.
services.accessibility.disableRules
services:
accessibility:
disableRules:
- color-contrastDescription: Rule IDs to disable.
Possible values: zero or more rule ID strings.
Required: no.
Default: not set.
services.accessibility.exclude
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
services:
memory:
enabled: trueDescription: Enables runtime memory injection.
Possible values: true or false.
Required: no.
Default: true.
services.memory.provider
services:
memory:
provider: localDescription: Memory storage provider.
Possible values: local.
Required: no.
Default: local.
services.memory.dir
services:
memory:
dir: agent-qa-memoryDescription: Directory used by local memory.
Possible values: a non-empty path string.
Required: no.
Default: the built-in local memory directory.
services.memory.minTrust
services:
memory:
minTrust: 0.3Description: 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
services:
memory:
maxInjections: 3Description: 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
services:
memory:
curatorEnabled: trueDescription: Enables the memory curator after runs.
Possible values: true or false.
Required: no.
Default: true.
services.memory.curatorLockTimeout
services:
memory:
curatorLockTimeout: 120000Description: Curator lock timeout in milliseconds.
Possible values: an integer of at least 1000.
Required: no.
Default: 120000.
services.memory.trustConfirmDelta
services:
memory:
trustConfirmDelta: 0.05Description: Trust increase applied when memory is confirmed.
Possible values: a number from 0 to 1.
Required: no.
Default: 0.05.
services.memory.trustContradictDelta
services:
memory:
trustContradictDelta: 0.10Description: Trust decrease applied when memory is contradicted.
Possible values: a number from 0 to 1.
Required: no.
Default: 0.10.
services.memory.ablationEnabled
services:
memory:
ablationEnabled: trueDescription: Enables memory ablation behavior.
Possible values: true or false.
Required: no.
Default: true.
services.memory.circuitBreakerEnabled
services:
memory:
circuitBreakerEnabled: trueDescription: Enables the memory circuit breaker.
Possible values: true or false.
Required: no.
Default: true.
services.memory.circuitBreakerWindowSize
services:
memory:
circuitBreakerWindowSize: 20Description: Window size for memory circuit checks.
Possible values: an integer of at least 5.
Required: no.
Default: 20.
services.memory.circuitBreakerBaselineSize
services:
memory:
circuitBreakerBaselineSize: 3Description: Baseline sample size for memory circuit checks.
Possible values: an integer of at least 2.
Required: no.
Default: 3.
services.memory.circuitBreakerThreshold
services:
memory:
circuitBreakerThreshold: 0.15Description: 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
registry:
llms:
- name: codexDescription: 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
registry:
llms:
- name: codex
provider: openai-subscriptionDescription: 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
registry:
llms:
- name: codex
provider: openai-subscription
model: gpt-5.5Description: Provider model name.
Possible values: any provider-supported model string.
Required: yes for each LLM entry.
Default: none.
registry.llms.baseURL
registry:
llms:
- name: local-openai
provider: openai-compatible
model: qwen2.5-vl
baseURL: http://localhost:11434/v1Description: 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
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-19Description: 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
registry:
llms:
- name: codex
provider: openai-subscription
model: gpt-5.5
screenshotSize: 50kbDescription: 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
registry:
llms:
- name: codex
provider: openai-subscription
model: gpt-5.5
effectiveResolution: 500Description: Optional positive integer describing effective image resolution.
Possible values: positive integers.
Required: no.
Default: not set.
registry.llms.contextWindow
registry:
llms:
- name: codex
provider: openai-subscription
model: gpt-5.5
contextWindow: 1mbDescription: 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
registry:
targets:
issue-tracker-web:
product: issue-trackerDescription: 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
registry:
targets:
issue-tracker-web:
platform: webDescription: Target platform.
Possible values: web, android, or ios.
Required: yes for each target.
Default: none.
registry.targets.url
registry:
targets:
issue-tracker-web:
platform: web
url: http://localhost:3000Description: Start URL for a web target.
Possible values: a URL string.
Required: yes when platform is web.
Default: none.
registry.targets.bundleId
registry:
targets:
ios-release:
platform: ios
bundleId: com.company.issuetrackerDescription: iOS bundle identifier for native iOS targets.
Possible values: string.
Required: no.
Default: not set.
registry.targets.appPackage
registry:
targets:
android-release:
platform: android
appPackage: com.company.issuetrackerDescription: Android package name for native Android targets.
Possible values: string.
Required: no.
Default: not set.
registry.targets.appActivity
registry:
targets:
android-release:
platform: android
appActivity: .MainActivityDescription: Android launch activity for native Android targets.
Possible values: string.
Required: no.
Default: not set.
registry.targets.app.path
registry:
targets:
android-release:
platform: android
app:
path: apps/android/release.apkDescription: 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
registry:
targets:
android-release:
platform: android
app:
browserstack: bs://uploaded-app-idDescription: 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
registry:
devices:
android-local:
platform: androidDescription: Device platform.
Possible values: android or ios.
Required: yes for each device profile.
Default: none.
registry.devices.transport
registry:
devices:
android-local:
platform: android
transport: localDescription: Device transport.
Possible values: local or browserstack.
Required: yes for each device profile.
Default: none.
registry.devices.match
registry:
devices:
android-local:
platform: android
transport: local
match:
appPackage: com.company.issuetrackerDescription: 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
registry:
providers:
browserstack:
project: issue-tracker-webDescription: 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
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
plugins:
auth:
- path: ./tools/agent-qa-auth-plugin.mjsDescription: 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
use:
browser:
name: chromiumDescription: 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
use:
browser:
headless: trueDescription: 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
use:
browser:
viewport:
width: 1280Description: Browser viewport width.
Possible values: number.
Required: no.
Default: not set by schema.
use.browser.viewport.height
use:
browser:
viewport:
height: 720Description: Browser viewport height.
Possible values: number.
Required: no.
Default: not set by schema.
use.mobile.appState
use:
mobile:
appState: preserveDescription: 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
use:
timeout:
step: 5mDescription: 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
use:
timeout:
test: 45mDescription: 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
use:
timeout:
navigation: 90sDescription: Default timeout for navigation actions.
Possible values: duration strings.
Required: yes when use.timeout is present.
Default: not set by schema.
use.healing.maxAttempts
use:
healing:
maxAttempts: 3Description: Default self-healing retry budget.
Possible values: number.
Required: yes when use.healing is present.
Default: not set by schema.
use.planner.maxSubActions
use:
planner:
maxSubActions: 12Description: Planner sub-action budget per step.
Possible values: number.
Required: yes when use.planner is present.
Default: not set by schema.
use.planner.previousStepCount
use:
planner:
previousStepCount: 6Description: 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
use:
logCapture:
console: trueDescription: Captures browser console logs.
Possible values: true or false.
Required: yes when use.logCapture is present.
Default: not set by schema.
use.logCapture.network
use:
logCapture:
network: trueDescription: Captures browser network logs.
Possible values: true or false.
Required: yes when use.logCapture is present.
Default: not set by schema.
use.cache
use:
cache: trueDescription: 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
use:
llm: codexDescription: Default LLM config name.
Possible values: the name of an entry in registry.llms.
Required: no.
Default: not set by schema.
use.parallel
use:
parallel: falseDescription: Allows parallel execution where supported.
Possible values: true or false.
Required: no.
Default: not set by schema.
analytics
analytics.privacy
analytics:
privacy: trueDescription: Privacy flag for analytics behavior.
Possible values: true.
Required: no.
Default: not set.
analytics.passRateScope.attributes
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
AGENT_QA_DASHBOARD_PORT=3110Overrides: services.dashboard.port.
AGENT_QA_MCP_PORT
AGENT_QA_MCP_PORT=3481Overrides: services.mcp.port.
AGENT_QA_CACHE_DIR
AGENT_QA_CACHE_DIR=.agent-qa/cacheOverrides: services.cache.dir.
AGENT_QA_CACHE_TTL
AGENT_QA_CACHE_TTL=7dOverrides: services.cache.ttl.
AGENT_QA_LOG_LEVEL
AGENT_QA_LOG_LEVEL=debugOverrides: services.logging.level.
AGENT_QA_HEADLESS
AGENT_QA_HEADLESS=falseOverrides: use.browser.headless.
Use agent-qa run --config-debug when you want to inspect the resolved config with source attribution.