> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qaos.machdel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Overview
> Understand how QAOS runs are configured and what each field controls.
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
```json theme={null}
{
"name": "string",
"projectId": "string",
"maxBudget": 5,
"qaosMode": true,
"qaosConfig": {
"startUrl": "string",
"subAgents": ["security", "uiux"],
"maxPages": 20,
"maxDepth": 3
},
"agentInfo": { "key": "value" }
}
```
```json theme={null}
{
"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.
```
"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.
```json theme={null}
"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
Use the QAOS dashboard to generate a config file through a guided form — no JSON editing required.
Write or edit the config file directly with the full field reference.