JSON Config Reference

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.

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

"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

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

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

Overview

Getting Started

Configuration

Running Tests

Issue Reference

Legal

JSON Config Reference

Full examples

QAOS Mode

Guided Mode

Root-level fields

`name` required

`projectId` required

`agentInfo` optional

`websiteOrigin` optional

`maxBudget` optional

`qaosMode` optional

`qaosConfig` required when `qaosMode: true`

`tasks` required unless `qaosMode: true`

Task fields

`description` required

`context` optional

`startUrl` required

`subAgents` optional

Common patterns

QAOS Mode — full site audit

Multi-step authentication flow

Security-focused admin audit

Accessibility-only UI/UX pass

Completion-only task (no evaluations)

Testing a local static site

​Full examples

​QAOS Mode

​Guided Mode

​Root-level fields

​name required

​projectId required

​agentInfo optional

​websiteOrigin optional

​maxBudget optional

​qaosMode optional

​qaosConfig required when qaosMode: true

​tasks required unless qaosMode: true

​Task fields

​description required

​context optional

​startUrl required

​subAgents optional

​Common patterns

​QAOS Mode — full site audit

​Multi-step authentication flow

​Security-focused admin audit

​Accessibility-only UI/UX pass

​Completion-only task (no evaluations)

​Testing a local static site

Full examples

QAOS Mode

Guided Mode

Root-level fields

`name` required

`projectId` required

`agentInfo` optional

`websiteOrigin` optional

`maxBudget` optional

`qaosMode` optional

`qaosConfig` required when `qaosMode: true`

`tasks` required unless `qaosMode: true`

Task fields

`description` required

`context` optional

`startUrl` required

`subAgents` optional

Common patterns

QAOS Mode — full site audit

Multi-step authentication flow

Security-focused admin audit

Accessibility-only UI/UX pass

Completion-only task (no evaluations)

Testing a local static site