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.

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

qaos-config.json
{
  "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

qaos-config.json
{
  "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. 
"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 under Projects → Settings. 
"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. 
"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.
"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. 
"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. 
"qaosMode": true

​
qaosConfig required when qaosMode: true

Type: object Configuration for the autonomous crawl. Only used when qaosMode is true.
FieldTypeRequiredDescription
startUrlstringYesThe URL the agent starts crawling from. Must include a recognized scheme (https://, http://, file://, a Windows drive path, or a Unix/Mac absolute path)
subAgentsarrayYesWhich agents to run: "security", "uiux", or both
maxPagesnumberNoMaximum number of pages to visit. Omit for no limit
maxDepthnumberNoMaximum link depth to follow from startUrl. Omit for no limit
"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. 
"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. 
"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.
"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. 
"subAgents": ["security", "uiux"]  // run both
"subAgents": ["security"]          // security only
"subAgents": ["uiux"]              // UI/UX only
"subAgents": []                    // flow validation only
AgentWhat 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

{
  "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

{
  "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

{
  "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

{
  "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. 
{
  "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. 
{
  "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"]
    }
  ]
}