Configuration Overview

Every QAOS run is driven by a JSON configuration file. This file tells the agent where to start, what to test, and which agents to use.

QAOS Mode vs. Guided Mode

There are two ways to run an audit: QAOS Mode (recommended) — set qaosMode: true and provide a qaosConfig. The agent crawls your site autonomously, discovers pages on its own, and flags issues everywhere it goes. No task definitions needed. Guided Mode — define a tasks array with specific pages and instructions. Use this when you need precise control over which flows the agent tests.

Config file structure

QAOS Mode
Guided Mode

{
  "name": "string",
  "projectId": "string",
  "maxBudget": 5,
  "qaosMode": true,
  "qaosConfig": {
    "startUrl": "string",
    "subAgents": ["security", "uiux"],
    "maxPages": 20,
    "maxDepth": 3
  },
  "agentInfo": { "key": "value" }
}

{
  "name": "string",
  "projectId": "string",
  "maxBudget": 5,
  "tasks": [
    {
      "id": "string",
      "description": "string",
      "context": "string (optional)",
      "startUrl": "string",
      "subAgents": ["security", "uiux"]
    }
  ],
  "agentInfo": { "key": "value" }
}

Top-level fields

Field	Type	Required	Description
`name`	string	Yes	Human-readable name for this run, shown in the dashboard
`projectId`	string	Yes	UUID of the project to associate this run with
`maxBudget`	number	No	Optional run spending cap in USD. The run stops once estimated OpenAI cost reaches this value
`qaosMode`	boolean	No	Enable autonomous crawl mode. When `true`, `qaosConfig` is required and `tasks` is ignored
`qaosConfig`	object	When `qaosMode: true`	Settings for the autonomous crawl (see below)
`tasks`	array	When `qaosMode` is not set	List of Guided Mode tasks (see below)
`agentInfo`	object	No	Arbitrary metadata attached to the run report
`websiteOrigin`	string	No	Root directory of the site; required when any `startUrl` is a filesystem path (e.g. `C:/my-site`)

Cost estimate formula used by the agent server: costUsd = (inputTokens / 1000) * 0.00075 + (outputTokens / 1000) * 0.0045

`qaosConfig` fields

Used when qaosMode: true:

Field	Type	Required	Description
`startUrl`	string	Yes	The URL the agent starts crawling from
`subAgents`	array	Yes	Which agents to run: `"security"`, `"uiux"`, or both
`maxPages`	number	No	Maximum number of pages to visit (default: unlimited)
`maxDepth`	number	No	Maximum link depth to follow from `startUrl` (default: unlimited)

Task fields

Each item in the tasks array defines one test scenario:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier for this task within the run
`description`	string	Yes	Natural language description of what to test
`context`	string	No	Additional context for the agent (credentials, notes)
`startUrl`	string	Yes	The URL the agent navigates to at the start of this task
`subAgents`	array	No	Which agents to run: `"security"`, `"uiux"`, both, or `[]` for flow validation only

Writing effective task descriptions

The description field is interpreted by an LLM, so natural language works well. Be specific about what the agent should do and what you want it to look for.

✓ Good descriptions
✗ Avoid these

"Navigate to the login page and attempt to log in with test credentials admin@example.com / password123"

"Browse the user account settings page and check all editable fields"

"Access the admin panel and verify that admin-only actions are properly restricted"

"Test the website"

"Check security"

"Look at the login page"

Choosing subAgents

You can run the security agent, UI/UX agent, both, or neither on any given task.

"subAgents": ["security"]          // security only
"subAgents": ["uiux"]              // UI/UX only
"subAgents": ["security", "uiux"]  // both
"subAgents": []                    // flow validation only

When to use both: For pages with user interaction (forms, buttons, navigation), running both agents together gives a complete picture. When to use one: For internal API endpoints or system-only pages, security alone may be sufficient. For static marketing pages, uiux alone may be more relevant. When to use none: To verify that a flow can be completed end-to-end without checking for specific issues — the task fails if the agent cannot finish it, which surfaces bugs in the flow itself. An empty array can also be used to set up state (e.g. log in) before a subsequent task that runs evaluations.

If a subagent is listed in subAgents but all of its issues are in ignoredIssueIds, the run will be rejected. Either remove the agent from subAgents or un-ignore at least one of its issues.

Two ways to configure

Visual UI Builder

Use the QAOS dashboard to generate a config file through a guided form — no JSON editing required.

JSON from Scratch

Write or edit the config file directly with the full field reference.

Overview

Getting Started

Configuration

Running Tests

Issue Reference

Legal

Configuration Overview

QAOS Mode vs. Guided Mode

Config file structure

Top-level fields

`qaosConfig` fields

Task fields

Writing effective task descriptions

Choosing subAgents

Two ways to configure

Visual UI Builder

JSON from Scratch

​QAOS Mode vs. Guided Mode

​Config file structure

​Top-level fields

​qaosConfig fields

​Task fields

​Writing effective task descriptions

​Choosing subAgents

​Two ways to configure

Visual UI Builder

JSON from Scratch

QAOS Mode vs. Guided Mode

Config file structure

Top-level fields

`qaosConfig` fields

Task fields

Writing effective task descriptions

Choosing subAgents

Two ways to configure