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 dashboard includes a guided config builder that generates a valid qaos-config.json for you. This is the fastest way to set up a new run, especially if you’re not familiar with the JSON format.

​
Accessing the builder

  1. Log in to the QAOS Dashboard
  2. Navigate to Projects and open or create a project
  3. Click New Run → Configure with UI

​
Step 1 — Name your run

Enter a descriptive name for this run. This name appears in your run history and reports, so make it identifiable: 
Production audit — March 2025
Login flow security check
Post-deploy accessibility review

​
Step 2 — Choose a mode

Select how you want the agent to explore your application:
  • Guided Mode — you define each task manually with a description and start URL. Best when you have specific flows to test.
  • QAOS Mode — the agent starts at a single URL and autonomously crawls your entire site, discovering pages on its own. Best for broad audits with minimal setup.

​
Step 2a — QAOS Mode configuration

If you selected QAOS Mode, fill in:
  • Website origin — the root of the site the agent begins crawling from (e.g. https://your-app.com or C:/my-site)
  • Subpath — the starting page within that origin (e.g. / or /index.html). Leave blank to start from the root.
  • Agents to run — toggle Security and/or UI/UX
  • Max pages (optional) — limit how many pages the agent visits
  • Max depth (optional) — limit how many link levels deep the agent follows from the start URL
The agent discovers and audits pages on its own — no tasks required. Skip to Step 3.

​
Step 2b — Add tasks (Guided Mode)

Click Add Task to define each test scenario. For each task, fill in:
1

Task description

Describe what the agent should do in natural language. Be specific about the user flow and what you want tested.Example: "Navigate to the checkout page, add an item, and proceed through the payment flow"
2

Website origin and subpath

Enter where the agent should begin this task using two fields:
  • Website origin — the root of the site (e.g. https://your-app.com or C:/my-site). Shared across all tasks; setting it on one task sets it for the whole run.
  • Subpath — the page-specific path within that origin (e.g. /shop/cart or /index.html).
The full start URL is constructed by combining both: https://your-app.com/shop/cart.
3

Agents to run

Toggle the Security and/or UI/UX agent for this task. Both are enabled by default.
  • Security — checks for vulnerabilities, access control issues, weak cryptography, etc.
  • UI/UX — checks for accessibility violations, UX issues, navigation problems, etc.
Leaving both unchecked is valid — the agent will still attempt to complete the task, but will not run any issue evaluations. This is primarily useful for verifying 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 (e.g. log in) before a subsequent task that does run evaluations.
If you select an agent but have ignored all of its issues in the Ignored issues section, saving or downloading the config will be blocked. Either un-ignore at least one issue for that agent or remove it from the task.
Repeat for each distinct area of your application you want to test.

​
Step 3 — Review and export

Once you’ve added all tasks, click Preview JSON to see the generated config file. You can:
  • Copy to clipboard — paste it into a file on your machine
  • Download — save it directly as qaos-config.json

​
Editing the generated config

The exported JSON is a standard QAOS config file. You can edit it freely — add more tasks, adjust descriptions, change agent selections, or add environment file references. See the JSON Reference for a complete field description.

​
Tips for good configs

Cover the full user journey. Create one task per major feature area: authentication, user profile, data listings, admin panels, checkout flows, etc.
Include authentication context. If your application requires login, add an authentication task first (e.g., “Log in with admin@example.com / password123”) before tasks that test authenticated pages.
Only test applications you own or have permission to test. See Terms of Use for the full policy.