Skip to main content

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.

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

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

​
Top-level fields

FieldTypeRequiredDescription
namestringYesHuman-readable name for this run, shown in the dashboard
projectIdstringYesUUID of the project to associate this run with
maxBudgetnumberNoOptional run spending cap in USD. The run stops once estimated OpenAI cost reaches this value
qaosModebooleanNoEnable autonomous crawl mode. When true, qaosConfig is required and tasks is ignored
qaosConfigobjectWhen qaosMode: trueSettings for the autonomous crawl (see below)
tasksarrayWhen qaosMode is not setList of Guided Mode tasks (see below)
agentInfoobjectNoArbitrary metadata attached to the run report
websiteOriginstringNoRoot 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:
FieldTypeRequiredDescription
startUrlstringYesThe URL the agent starts crawling from
subAgentsarrayYesWhich agents to run: "security", "uiux", or both
maxPagesnumberNoMaximum number of pages to visit (default: unlimited)
maxDepthnumberNoMaximum link depth to follow from startUrl (default: unlimited)

​
Task fields

Each item in the tasks array defines one test scenario:
FieldTypeRequiredDescription
idstringYesUnique identifier for this task within the run
descriptionstringYesNatural language description of what to test
contextstringNoAdditional context for the agent (credentials, notes)
startUrlstringYesThe URL the agent navigates to at the start of this task
subAgentsarrayNoWhich 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"

​
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.