> ## 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.
# JSON Config Reference
> Complete reference for every field in the QAOS configuration file.
The QAOS config file is a JSON document that fully specifies a test run. Save it anywhere on your system and pass its path to `qaos run --config`.
***
## Full examples
### QAOS Mode
```json qaos-config.json theme={null}
{
"name": "Full Site Audit — v2.1",
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"maxBudget": 10,
"agentInfo": {
"environment": "staging",
"triggeredBy": "ci-pipeline",
"branch": "main"
},
"qaosMode": true,
"qaosConfig": {
"startUrl": "https://staging.example.com",
"subAgents": ["security", "uiux"],
"maxPages": 50,
"maxDepth": 4
}
}
```
### Guided Mode
```json qaos-config.json theme={null}
{
"name": "Full Site Audit — v2.1",
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"maxBudget": 10,
"agentInfo": {
"environment": "staging",
"triggeredBy": "ci-pipeline",
"branch": "main"
},
"tasks": [
{
"description": "Navigate to the login page and sign in with credentials admin@example.com / password123",
"context": "Use the test account. The login page has a standard username/password form.",
"startUrl": "https://staging.example.com/login",
"subAgents": ["security", "uiux"]
},
{
"description": "Browse the main dashboard and interact with the data tables",
"startUrl": "https://staging.example.com/dashboard",
"subAgents": ["security", "uiux"]
},
{
"description": "Access the admin panel and attempt to perform admin actions as a regular user",
"startUrl": "https://staging.example.com/admin",
"subAgents": ["security"]
},
{
"description": "Navigate to user account settings, edit the profile, and change the password",
"startUrl": "https://staging.example.com/settings",
"subAgents": ["security", "uiux"]
}
]
}
```
***
## Root-level fields
### `name` required
**Type:** `string`
A human-readable label for this run, shown in the dashboard and reports. Use descriptive names that identify the scope and context.
```json theme={null}
"name": "Production security audit — Q1 2025"
```
***
### `projectId` required
**Type:** `string` (UUID)
The ID of the QAOS project this run belongs to. Find project IDs in the [Dashboard](https://qaos.machdel.com) under **Projects → Settings**.
```json theme={null}
"projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```
***
### `agentInfo` optional
**Type:** `object`
Arbitrary key-value metadata attached to the run and visible in the report. Use this to track context like environment name, CI pipeline info, or triggering user.
```json theme={null}
"agentInfo": {
"environment": "staging",
"commit": "abc1234",
"triggeredBy": "github-actions"
}
```
***
### `websiteOrigin` optional
**Type:** `string`
The root directory of the website being tested. Only required when any `startUrl` is a **filesystem path** — either a `file://` URL or a Windows local drive path (e.g. `C:/my-site`).
When set, every `startUrl` (across all tasks and `qaosConfig`) must begin with this value. Paths are compared using forward slashes, so `C:\my-site` and `C:/my-site` are treated the same.
For HTTP and HTTPS URLs, you can omit this field entirely — it is not used.
If any `startUrl` is a filesystem path, the run will be rejected unless `websiteOrigin` is set to the root directory of the site.
```json theme={null}
"websiteOrigin": "C:/my-site"
```
***
### `maxBudget` optional
**Type:** `number`
Maximum run budget in USD. When set, the run is aborted as soon as the estimated OpenAI cost reaches this value.
```json theme={null}
"maxBudget": 5
```
Cost formula used by the server:
`costUsd = (inputTokens / 1000) * 0.00075 + (outputTokens / 1000) * 0.0045`
***
### `qaosMode` optional
**Type:** `boolean`
When `true`, enables autonomous crawl mode. The agent starts at `qaosConfig.startUrl`, discovers pages on its own, and audits everything it finds. The `tasks` array is ignored.
```json theme={null}
"qaosMode": true
```
***
### `qaosConfig` required when `qaosMode: true`
**Type:** `object`
Configuration for the autonomous crawl. Only used when `qaosMode` is `true`.
| Field | Type | Required | Description |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `startUrl` | string | Yes | The URL the agent starts crawling from. Must include a recognized scheme (`https://`, `http://`, `file://`, a Windows drive path, or a Unix/Mac absolute path) |
| `subAgents` | array | Yes | Which agents to run: `"security"`, `"uiux"`, or both |
| `maxPages` | number | No | Maximum number of pages to visit. Omit for no limit |
| `maxDepth` | number | No | Maximum link depth to follow from `startUrl`. Omit for no limit |
```json theme={null}
"qaosConfig": {
"startUrl": "https://app.example.com",
"subAgents": ["security", "uiux"],
"maxPages": 20,
"maxDepth": 3
}
```
***
### `tasks` required unless `qaosMode: true`
**Type:** `array`
The list of Guided Mode tasks to execute. Tasks run sequentially in the order they are defined. Required when `qaosMode` is not set. Ignored when `qaosMode: true`.
***
## Task fields
Each object in the `tasks` array:
### `description` required
**Type:** `string`
A natural language description of what this task should do. The agent interprets this to decide which actions to take, which pages to navigate to, and what to look for. More specific descriptions yield better results.
```json theme={null}
"description": "Go to the checkout page, add item #SKU-001 to the cart, proceed to payment, and check the payment form for security issues"
```
***
### `context` optional
**Type:** `string`
Additional background information the agent should be aware of when executing this task. Useful for providing credentials, explaining application-specific behavior, or flagging known limitations.
```json theme={null}
"context": "Use test credentials test@example.com / testpass123. The dashboard may take 2-3 seconds to load data."
```
***
### `startUrl` required
**Type:** `string`
The URL the agent navigates to at the beginning of this task. Must include a recognized scheme:
* **Web URLs**: `https://` or `http://`
* **Filesystem paths**: `file://` URL, a Windows drive path (`C:/my-site/page.html`), or a Unix/Mac absolute path (`/home/user/site/page.html`)
Omitting the scheme (e.g. writing `example.com` instead of `https://example.com`) will cause the run to be rejected. Always include the full scheme.
```json theme={null}
"startUrl": "https://app.example.com/login"
```
***
### `subAgents` optional
**Type:** `array` of `"security"` | `"uiux"`
Which agent modules to activate for this task. Accepts an array containing one, both, or neither value. An empty array is valid — the agent will still navigate and attempt to complete the task description, but will not run any issue evaluations. This is primarily useful for validating that a flow can be completed end-to-end (the task fails if the agent cannot finish it). It can also be used to set up state before a subsequent task.
```json theme={null}
"subAgents": ["security", "uiux"] // run both
"subAgents": ["security"] // security only
"subAgents": ["uiux"] // UI/UX only
"subAgents": [] // flow validation only
```
| Agent | What it checks |
| ------------ | ------------------------------------------------------------------------------------- |
| `"security"` | Access control, injection, cryptography, session management, information disclosure |
| `"uiux"` | Accessibility, form usability, keyboard navigation, color contrast, responsive design |
If a subagent is included in `subAgents` but **all** of its issues are listed in `ignoredIssueIds`, the run will be rejected with an error. Either remove the agent from `subAgents` or un-ignore at least one of its issues.
***
## Common patterns
### QAOS Mode — full site audit
```json theme={null}
{
"name": "Full site audit",
"projectId": "your-project-id",
"qaosMode": true,
"qaosConfig": {
"startUrl": "https://app.example.com",
"subAgents": ["security", "uiux"],
"maxPages": 50,
"maxDepth": 4
}
}
```
### Multi-step authentication flow
```json theme={null}
{
"tasks": [
{
"description": "Log in with username admin@example.com and password TestPass123",
"startUrl": "https://app.example.com/login",
"subAgents": ["security", "uiux"]
},
{
"description": "Browse the authenticated dashboard and user profile page",
"startUrl": "https://app.example.com/dashboard",
"subAgents": ["security", "uiux"]
}
]
}
```
### Security-focused admin audit
```json theme={null}
{
"tasks": [
{
"description": "Try to access the admin panel at /admin without authentication",
"startUrl": "https://app.example.com/admin",
"subAgents": ["security"]
},
{
"description": "Log in as a regular user and attempt to access admin-only endpoints",
"startUrl": "https://app.example.com/login",
"context": "Regular user credentials: user@example.com / UserPass123",
"subAgents": ["security"]
}
]
}
```
### Accessibility-only UI/UX pass
```json theme={null}
{
"tasks": [
{
"description": "Review the homepage for accessibility issues",
"startUrl": "https://app.example.com/",
"subAgents": ["uiux"]
},
{
"description": "Navigate through the registration form and contact form for accessibility issues",
"startUrl": "https://app.example.com/register",
"subAgents": ["uiux"]
}
]
}
```
### Completion-only task (no evaluations)
Use `"subAgents": []` to verify that a flow can be completed without checking for specific issues. The task fails if the agent cannot finish it, surfacing bugs in the flow itself. It can also be used to set up state (e.g. log in) before a subsequent task that does run evaluations.
```json theme={null}
{
"tasks": [
{
"description": "Log in to the website",
"context": "Use test credentials test@example.com / testpass123.",
"startUrl": "https://app.example.com/login",
"subAgents": []
},
{
"description": "Browse the authenticated dashboard",
"startUrl": "https://app.example.com/dashboard",
"subAgents": ["security", "uiux"]
}
]
}
```
### Testing a local static site
Use filesystem paths when testing a locally-served static website. Set `websiteOrigin` to the root directory and use full paths for each task.
```json theme={null}
{
"name": "Local site audit",
"projectId": "your-project-id",
"websiteOrigin": "C:/my-site",
"tasks": [
{
"description": "Review the home page for accessibility issues",
"startUrl": "C:/my-site/index.html",
"subAgents": ["uiux"]
},
{
"description": "Review the contact form for accessibility and security issues",
"startUrl": "C:/my-site/contact.html",
"subAgents": ["security", "uiux"]
}
]
}
```