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.

This guide walks you through running a complete audit on your web application from scratch.

​
1. Create an account and project

Before anything else, sign up for a QAOS account and create a project from the QAOS Dashboard. You’ll need your project ID in the next steps.

​
2. Install and authenticate

If you haven’t already, install the CLI and log in: 
npx qaos auth --ui
See Installation and Authentication for detailed instructions.

​
3. Create a config file

Create a file named qaos-config.json in your project directory. With QAOS Mode, the agent crawls your entire site automatically — no need to define individual tasks:
qaos-config.json
{
  "name": "My First Audit",
  "projectId": "your-project-id-here",
  "qaosMode": true,
  "qaosConfig": {
    "startUrl": "https://your-app.com",
    "subAgents": ["security", "uiux"]
  }
}
Replace your-project-id-here with a project ID from the QAOS Dashboard, and set startUrl to your application’s home page.
Need more control over which specific pages to test? You can use Guided Mode instead of QAOS Mode. See Configuration Overview.

​
4. Start the run

npx qaos run --config ./qaos-config.json
The CLI will:
  1. Connect to the QAOS server
  2. Launch a headless browser
  3. Start crawling from the provided startUrl
  4. Autonomously discover and navigate pages across your site
  5. Run the security and UI/UX agents on each page it visits
  6. Stream findings to your terminal in real time
Add --headed to watch the browser in real time as it navigates your app:
npx qaos run --config ./qaos-config.json --headed
Agent limitations: The QAOS agent operates as an automated browser and has some inherent constraints:
  • File uploads are not supported. Pages that require file input will be skipped.
  • Third-party authentication (e.g. “Sign in with Google”) cannot be completed unless it is mocked in your environment. Use a standard username/password login, or set up a mock OAuth provider, so the agent can authenticate.
  • Bot detection may flag the agent and block navigation. Disable any bot protection (WAF rules, rate limiting, browser fingerprinting) in your test environment before running.
  • CAPTCHA / bot challenges will block the agent. Disable them in your test environment or use an allowlisted IP.

​
5. View the report

Open the report URL printed at the end of the run, or navigate to Reports in the QAOS Dashboard. The report includes:
  • Every detected issue with severity, description, and location
  • Reproduction context
  • Fix recommendations for each issue

​
Next steps

Configure a run

Learn all configuration options and how to write effective task descriptions.

Issue reference

Understand every issue type QAOS detects and how to fix them.